MT-23076: support expires_at for api token create and reset

[oshchyhol]

Motivation

MT-23076

The Mailtrap API token endpoints now accept an optional expires_at. This exposes it in the Ruby SDK so tokens can be created or reset with an explicit expiry, with the server default, or as never-expiring.

Changes

• ApiTokensAPI#create accepts expires_at (the createApiToken request param): omit for the server default (a 1-year default is being rolled out), pass an ISO 8601 date-time for an explicit expiry, or explicit nil for a token that never expires
• ApiTokensAPI#reset accepts an optional options hash with expires_at (the resetApiToken request body, which is optional in the spec); with no options it still sends no request body at all
• the serialized body distinguishes a missing expires_at key from "expires_at": null – no client-side date validation, invalid values are rejected by the server with 422
• specs assert the exact serialized request body for each case; VCR cassettes for the new examples are hand-crafted against the OpenAPI spec (the server feature flag is not enabled in production yet), so they should be re-recorded with bin/record-vcr once it is
• readme: added the missing API Tokens and Permissions example links under "General"

How to test

• api_tokens.create(name: ..., resources: [...]) without expires_at – the request body has no expires_at key and the token is created exactly as before
• api_tokens.create(..., expires_at: '2027-06-01T00:00:00Z') – the request body contains "expires_at":"2027-06-01T00:00:00Z" and the response token has that expiry
• api_tokens.create(..., expires_at: nil) – the request body contains "expires_at":null and the response token never expires
• api_tokens.create(..., expires_at: '2020-01-01T00:00:00Z') (past date) – raises Mailtrap::Error from the server 422
• api_tokens.reset(token_id) with no options – no request body is sent at all (same as the previous SDK version) and a new token is returned
• api_tokens.reset(token_id, expires_at: '2027-06-01T00:00:00Z') and api_tokens.reset(token_id, expires_at: nil) – the body is exactly {"expires_at":"2027-06-01T00:00:00Z"} / {"expires_at":null}
• api_tokens.create(unknown: true) and api_tokens.reset(token_id, unknown: true) – raise ArgumentError before any request is made

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 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: abeb779a-2920-4afa-af84-9984d1b7c8af

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