MT-23076: document api token expiration

[oshchyhol]

Motivation

MT-23076

API tokens now expire. createApiToken accepts an optional expires_at, resetApiToken gains an optional request body with the same param, and permission updates on an expired token are rejected. The spec needs to describe all of it.

Changes

• createApiToken: new optional nullable expires_at (ISO 8601 date-time) on CreateApiTokenRequest, plus the request example and the operation description – omitted means the token expires 1 year after creation, null means it never expires, and values must be no more than 5 years ahead
• resetApiToken: new optional request body carrying the same expires_at param, plus a cURL sample that sends it; the description now says already-expired tokens cannot be reset (422) instead of the old "only tokens with no expiration set can be reset"
• updatePermissions: documented the 422 response and the reason for it (permissions of an expired API token cannot be updated)
• fixed the account-access ApiToken specifier in getAllUsersInAccount: the field is masked_token (the token value with all but the last characters masked), not token – the API has never returned a full token value there

How to test

• the spec lints clean in CI
• in the rendered reference, "Create API token" shows expires_at as an optional nullable date-time with the 1-year default and 5-year cap described, and the request example includes it
• "Reset API token" shows an optional request body with expires_at and the cURL sample sending it, and states that expired tokens cannot be reset
• "Manage permissions" lists a 422 response
• "List users and tokens" shows masked_token on the API token specifier, matching what the endpoint actually returns
• against the deployed API: POST /api/api_tokens with no expires_at, with a date-time, and with null all behave as documented, and a past date returns 422

Companion PRs

• falcon – railsware/falcon#10763
• nodejs – MT-23076: support expires_at on api token create and reset mailtrap-nodejs#149
• mcp – MT-23076: support expires_at on the api token tools mailtrap-mcp#136
• php – MT-23076: support api token expiration in create and reset mailtrap-php#75
• python – MT-23076: support api token expiration in create and reset mailtrap-python#77
• ruby – MT-23076: support expires_at for api token create and reset mailtrap-ruby#122
• java – MT-23076: support api token expiration mailtrap-java#68
• dotnet – MT-23076: expose api token expiration in create and reset requests mailtrap-dotnet#253
• go – MT-23076: support api token expiration mailtrap-go#28
• cli – MT-23076: add --expires-at to tokens create and reset mailtrap-cli#12

Caveat: merge only after falcon deploys MT-23076 and zap_api_token_expiration is enabled in production – the docs describe the 1-year default, which only applies once the flag is on.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3d11cabc-9079-4ea7-b349-8c6785cdee43

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

Updates the Account Management OpenAPI spec to document newly introduced API token expiration behavior, including request parameters, validation rules, and related 422 error cases.

Changes:

• Documented expires_at (optional, nullable, date-time) for createApiToken, including request example and expiry semantics.
• Added an optional request body to resetApiToken to accept expires_at, updated cURL sample, and documented 422 behavior for expired tokens.
• Documented 422 for permission updates on expired API tokens, and corrected the account-access ApiToken specifier field to masked_token.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.