MT-23076: support api token expiration

[oshchyhol]

Motivation

MT-23076

The API token endpoints now accept an optional expires_at. This exposes it in the Java SDK so tokens can be created or reset with an explicit expiration, with no expiration, or with the server default.

Changes

• new TokenExpiration wrapper with TokenExpiration.at(OffsetDateTime) and TokenExpiration.never() factories; it pre-formats the value to an ISO 8601 string (raw OffsetDateTime fields would serialize as numeric timestamps with the SDK's ObjectMapper settings)
• CreateApiTokenRequest (createApiToken operation): optional expires_at param – omitted field keeps the key out of the JSON, never() sends "expires_at": null, at(...) sends the date-time string; the existing (name, resources) constructor still compiles
• new ResetApiTokenRequest and a resetApiToken(accountId, id, request) overload (resetApiToken operation, request body is optional in the spec); the existing no-arg overload still posts no body
• no client-side date validation – past, unparseable, or more-than-5-years-ahead values are rejected by the server with 422
• ApiTokenSpecifier (account accesses): added masked_token, which the spec defines for the ApiToken specifier
• tests asserting the exact serialized request bodies for all three expiration states, plus fixtures and an updated ApiTokensExample

How to test

• createApiToken without expiresAt – request body has no expires_at key; token is created (server assigns the default expiration where the flag is enabled)
• createApiToken with TokenExpiration.never() – request body contains "expires_at": null; created token has expiresAt null
• createApiToken with TokenExpiration.at(OffsetDateTime.parse("2027-06-01T00:00:00Z")) – request body contains "expires_at": "2027-06-01T00:00:00Z"; created token returns that expiresAt
• createApiToken with a past or more-than-5-years-ahead expiration – call throws HttpClientException with status 422
• resetApiToken(accountId, id, new ResetApiTokenRequest(TokenExpiration.never())) – posts {"expires_at": null}; new token never expires
• existing calls unchanged: new CreateApiTokenRequest(name, resources) and resetApiToken(accountId, id) compile as before, the reset posts no body, and both succeed exactly as on main

Companion PRs

• other 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: 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
• falcon PR railsware/falcon#10763
• spec PR MT-23076: document api token expiration mailtrap-openapi#51

Caveat: release/merge only after falcon deploys MT-23076 and zap_api_token_expiration is enabled in production.

[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: 46e2823e-9890-4be8-875e-85812998d771

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