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 PR railsware/falcon#10763
• MT-23076 SDK PRs: MT-23076: support expires_at on api token create and reset mailtrap-nodejs#149, MT-23076: support expires_at on the api token tools mailtrap-mcp#136, MT-23076: support api token expiration in create and reset mailtrap-php#75, MT-23076: support api token expiration in create and reset mailtrap-python#77, MT-23076: support expires_at for api token create and reset mailtrap-ruby#122, MT-23076: support api token expiration mailtrap-java#68, MT-23076: expose api token expiration in create and reset requests mailtrap-dotnet#253, MT-23076: support api token expiration mailtrap-go#28, 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

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 279db6c9-8711-4079-97bd-ad36d7d17977

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}