MT-23076: support api token expiration in create and reset

[oshchyhol]

Motivation

MT-23076

The API token endpoints now accept an optional expires_at value. This exposes it in the SDK so users can create or reset tokens with a specific expiry, no expiry, or the server default.

Changes

• new TokenExpiration value object (src/DTO/Request/ApiToken/TokenExpiration.php) with TokenExpiration::at(DateTimeInterface|string) and TokenExpiration::never() named constructors
• createApiToken (OpenAPI createApiToken, CreateApiTokenRequest.expires_at) takes an optional ?TokenExpiration $expiration – argument omitted → no expires_at key in the body (server default, a 1-year default is being rolled out), never() → "expires_at": null (never expires), at(...) → the given ISO 8601 date-time
• resetApiToken (OpenAPI resetApiToken, request body is now optional with the same expires_at param) takes the same optional argument – without it the request still has no body at all, unchanged from the previous release
• no client-side date validation – past, unparseable, or more-than-5-years-ahead values are rejected by the server with 422 and surface as HttpClientException
• examples/api-tokens/all.php shows the new argument; README and examples index now list the api-tokens example under General API

How to test

• createApiToken($name, $permissions) without the new argument – the request body contains only name and resources (no expires_at key), the token is created
• resetApiToken($id) without the new argument – the request is sent with no body at all, exactly as before this change, and returns the new token value
• createApiToken($name, $permissions, TokenExpiration::at('2027-06-01T00:00:00Z')) – the body contains "expires_at": "2027-06-01T00:00:00Z" and the response echoes that expiry
• TokenExpiration::at(new DateTimeImmutable('2027-06-01T00:00:00+00:00')) – the DateTime is serialized as an ISO 8601 string in the body
• createApiToken(..., TokenExpiration::never()) and resetApiToken($id, TokenExpiration::never()) – the body contains "expires_at": null and the response token has expires_at: null
• TokenExpiration::at('2020-01-01T00:00:00Z') (a past date) on create or reset – the server responds 422 and the SDK throws HttpClientException with the server error message

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-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
• 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: bd3b7bbd-2a61-4747-b7f9-77f791f170a5

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