From 60fad2ed0256e0547d315f9f25953e0d0d468468 Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Thu, 30 Jul 2026 19:43:16 +0200 Subject: [PATCH 1/3] MT-23076: document expires_at on API token create and reset --- specs/account-management.openapi.yml | 49 +++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 5 deletions(-) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index 72b805c..ce9f744 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -408,6 +408,7 @@ paths: Manage user or token permissions. For this endpoint, you should send an array of objects (in JSON format) as the body of the request. If you send a combination of **resource_type** and **resource_id** that already exists, the permission is **updated**. If the combination doesn't exist, the permission is **created**. + Permissions of an expired API token cannot be updated; such requests are rejected with a 422 error. tags: - Permissions x-codeSamples: @@ -594,6 +595,8 @@ paths: $ref: '#/components/responses/PERMISSION_DENIED' '404': $ref: '#/components/responses/NOT_FOUND' + '422': + $ref: '#/components/responses/UNPROCESSABLE_ENTITY' parameters: - schema: type: integer @@ -810,7 +813,10 @@ paths: post: operationId: createApiToken summary: Create API token - description: Creates a new API token for the account with the given name and resource permissions. + description: |- + Creates a new API token for the account with the given name and resource permissions. + Unless `expires_at` is provided, the token expires 1 year after creation. + Pass `"expires_at": null` to create a token that never expires. tags: - API Tokens x-codeSamples: @@ -822,6 +828,7 @@ paths: -H 'Content-Type: application/json' \ -d '{ "name": "My API Token", + "expires_at": "2027-06-01T00:00:00Z", "resources": [ {"resource_type": "account", "resource_id": 3229, "access_level": 100} ] @@ -1157,7 +1164,9 @@ paths: Expires the requested token and creates a new token with the same permissions. The old token stops working after a short grace period. The response includes the new token value (store it securely; it is only returned once). - Only tokens that have not already been reset (no expiration set) can be reset. + Unless `expires_at` is provided, the new token expires 1 year after the reset. + Pass `"expires_at": null` to create a token that never expires. + Tokens that have already expired cannot be reset (returns a 422 error). tags: - API Tokens x-codeSamples: @@ -1165,7 +1174,9 @@ paths: label: cURL source: | curl -X POST https://mailtrap.io/api/api_tokens/{id}/reset \ - -H 'Authorization: Bearer YOUR_API_KEY' + -H 'Authorization: Bearer YOUR_API_KEY' \ + -H 'Content-Type: application/json' \ + -d '{"expires_at": "2027-06-01T00:00:00Z"}' - lang: javascript label: Node.js source: | @@ -1246,6 +1257,24 @@ paths: System.out.println(token); parameters: - $ref: '#/components/parameters/api_token_id' + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + expires_at: + type: string + format: date-time + nullable: true + description: |- + When the new token expires (ISO 8601 date-time, must be in the future). + If omitted, the new token expires 1 year after the reset. + Pass null to create a token that never expires. + Past or unparseable values are rejected with a 422 error. + example: + expires_at: '2027-06-01T00:00:00Z' responses: '200': description: New API token (includes full token value once) @@ -1790,9 +1819,9 @@ components: type: string description: Describes the origin of the token example: System - token: + masked_token: type: string - description: The token value + description: The token value with all but the last characters masked expires_at: type: string format: date-time @@ -2006,6 +2035,15 @@ components: name: type: string description: Display name for the token + expires_at: + type: string + format: date-time + nullable: true + description: |- + When the token expires (ISO 8601 date-time, must be in the future). + If omitted, the token expires 1 year after creation. + Pass null to create a token that never expires. + Past or unparseable values are rejected with a 422 error. resources: type: array description: Permissions to assign to the token @@ -2013,6 +2051,7 @@ components: $ref: '#/components/schemas/ResourcePermissionInput' example: name: My API Token + expires_at: '2027-06-01T00:00:00Z' resources: - resource_type: account resource_id: 3229 From 7e117c9012e1df96640465a368af79a9e59cc0ab Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Mon, 3 Aug 2026 13:00:45 +0200 Subject: [PATCH 2/3] MT-23076: document the 5-year expiration cap --- specs/account-management.openapi.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index ce9f744..421f6e4 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -1270,6 +1270,7 @@ paths: nullable: true description: |- When the new token expires (ISO 8601 date-time, must be in the future). + Must be no more than 5 years in the future. If omitted, the new token expires 1 year after the reset. Pass null to create a token that never expires. Past or unparseable values are rejected with a 422 error. @@ -2041,6 +2042,7 @@ components: nullable: true description: |- When the token expires (ISO 8601 date-time, must be in the future). + Must be no more than 5 years in the future. If omitted, the token expires 1 year after creation. Pass null to create a token that never expires. Past or unparseable values are rejected with a 422 error. From e75ba559cff77d9ae8aefeedc2bf7b5c17e762ac Mon Sep 17 00:00:00 2001 From: Alex Shchyhol Date: Mon, 24 Aug 2026 17:06:24 +0200 Subject: [PATCH 3/3] MT-23076: mention the 5-year cap in the token create and reset descriptions --- specs/account-management.openapi.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specs/account-management.openapi.yml b/specs/account-management.openapi.yml index 421f6e4..51237f7 100644 --- a/specs/account-management.openapi.yml +++ b/specs/account-management.openapi.yml @@ -817,6 +817,8 @@ paths: Creates a new API token for the account with the given name and resource permissions. Unless `expires_at` is provided, the token expires 1 year after creation. Pass `"expires_at": null` to create a token that never expires. + `expires_at` must be in the future and no more than 5 years ahead; + past or unparseable values are rejected with a 422 error. tags: - API Tokens x-codeSamples: @@ -1166,6 +1168,8 @@ paths: the new token value (store it securely; it is only returned once). Unless `expires_at` is provided, the new token expires 1 year after the reset. Pass `"expires_at": null` to create a token that never expires. + `expires_at` must be in the future and no more than 5 years ahead; + past or unparseable values are rejected with a 422 error. Tokens that have already expired cannot be reset (returns a 422 error). tags: - API Tokens