MT-23076: expose api token expiration in create and reset requests

[oshchyhol]

Motivation

MT-23076 – the Mailtrap API token endpoints now accept an optional expires_at value. This exposes it in the .NET SDK.

Changes

• new ApiTokenExpiration type with a custom JSON converter implementing the tri-state contract: property unset – expires_at key omitted from the body (server default, a 1-year default is being rolled out behind a feature flag); ApiTokenExpiration.Never – explicit "expires_at": null (token never expires); ApiTokenExpiration.At(...) – ISO 8601 date-time string
• CreateApiTokenRequest.ExpiresAt for the createApiToken operation (optional nullable expires_at in the request body)
• new ResetApiTokenRequest and an IApiTokenResource.Reset(ResetApiTokenRequest, CancellationToken) overload for the resetApiToken operation, whose request body is now optional; the existing parameterless Reset() keeps sending no body
• no client-side date validation – past, unparseable, or more-than-5-years-ahead values are rejected by the API with 422
• Specifier.MaskedToken – the account-access ApiToken specifier has masked_token in the spec, which the SDK model was missing
• unit and integration tests covering the three serialization cases, the unchanged no-body reset, and the 422 error path
• api tokens example extended with expiration usage

Note: adding a member to IApiTokenResource is source-breaking for external implementors of that interface.

How to test

• call client.Account(id).ApiTokens().Create(request) without setting ExpiresAt – the request body contains no expires_at key; with the server flag enabled the created token gets the default 1-year expires_at in the response
• create with ExpiresAt = ApiTokenExpiration.Never – the request body contains "expires_at": null and the response has expires_at: null
• create with ExpiresAt = ApiTokenExpiration.At(DateTimeOffset.Parse("2027-06-01T00:00:00Z")) – the request body contains the ISO date-time and the response echoes it
• create with a past date – the call throws HttpRequestFailedException with status 422
• call apiToken.Reset() (parameterless) – the request is sent without a body and succeeds exactly as before this change
• call apiToken.Reset(new ResetApiTokenRequest { ExpiresAt = ApiTokenExpiration.Never }) – the request body is {"expires_at":null} and the new token never expires
• list tokens and get token details – expires_at is returned in responses as before

Companion PRs

• falcon – railsware/falcon#10763
• spec – MT-23076: document api token expiration mailtrap-openapi#51
• 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
• 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: 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: b4443237-18a9-4205-b8a0-4a7940bb3f63

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