# API Tokens

## List API tokens

> Returns all API tokens visible to the current API token.

```json
{"openapi":"3.1.0","info":{"title":"Account Management","version":"2.0.0"},"tags":[{"name":"API Tokens"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"account_id":{"description":"Unique account ID","name":"account_id","in":"path","required":true,"schema":{"type":"integer","format":"int64","minimum":1}}},"schemas":{"ApiToken":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"API token ID"},"name":{"type":"string","description":"Token display name"},"last_4_digits":{"type":"string","description":"Last 4 characters of the token (full token is only shown on create or reset)"},"created_by":{"type":"string","description":"Name of the user or token that created this token"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the token expires (ISO 8601); null if the token does not expire"},"resources":{"type":"array","description":"Permissions granted to this token","items":{"$ref":"#/components/schemas/ResourcePermission"}}}},"ResourcePermission":{"type":"object","properties":{"resource_type":{"type":"string","enum":["account","project","inbox","sending_domain"],"description":"Resource type for this permission"},"resource_id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Resource identifier"},"access_level":{"type":"integer","enum":[10,100],"description":"10 = viewer, 100 = admin."}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}}}},"paths":{"/api/accounts/{account_id}/api_tokens":{"get":{"operationId":"listApiTokens","summary":"List API tokens","description":"Returns all API tokens visible to the current API token.","tags":["API Tokens"],"parameters":[{"$ref":"#/components/parameters/account_id"}],"responses":{"200":{"description":"List of API tokens","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiToken"}}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"}}}}}}
```

## Create API token

> Creates a new API token for the account with the given name and resource permissions.

```json
{"openapi":"3.1.0","info":{"title":"Account Management","version":"2.0.0"},"tags":[{"name":"API Tokens"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"account_id":{"description":"Unique account ID","name":"account_id","in":"path","required":true,"schema":{"type":"integer","format":"int64","minimum":1}}},"schemas":{"CreateApiTokenRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Display name for the token"},"resources":{"type":"array","description":"Permissions to assign to the token","items":{"$ref":"#/components/schemas/ResourcePermissionInput"}}}},"ResourcePermissionInput":{"type":"object","required":["resource_type","resource_id","access_level"],"properties":{"resource_type":{"$ref":"#/components/schemas/ResourceType"},"resource_id":{"oneOf":[{"type":"integer"},{"type":"string"}]},"access_level":{"$ref":"#/components/schemas/AccessLevel"}}},"ResourceType":{"type":"string","enum":["account","project","inbox","sending_domain"],"description":"Resource type for API token permissions."},"AccessLevel":{"type":"integer","enum":[10,100],"description":"10 = viewer, 100 = admin."},"ApiTokenWithToken":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"API token ID"},"name":{"type":"string","description":"Token display name"},"last_4_digits":{"type":"string","description":"Last 4 characters of the token (full token is only shown on create or reset)"},"created_by":{"type":"string","description":"Name of the user or token that created this token"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the token expires (ISO 8601); null if the token does not expire"},"resources":{"type":"array","description":"Permissions granted to this token","items":{"$ref":"#/components/schemas/ResourcePermission"}},"token":{"type":"string","description":"Full token value (only returned on create or reset; store securely)"}}},"ResourcePermission":{"type":"object","properties":{"resource_type":{"type":"string","enum":["account","project","inbox","sending_domain"],"description":"Resource type for this permission"},"resource_id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Resource identifier"},"access_level":{"type":"integer","enum":[10,100],"description":"10 = viewer, 100 = admin."}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"title":"UnprocessableEntity","type":"object","properties":{"errors":{"type":"object","description":"Validation errors per attribute. Entire record errors are under `base` key."}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"UNPROCESSABLE_ENTITY":{"description":"Validation error or other business rule violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/accounts/{account_id}/api_tokens":{"post":{"operationId":"createApiToken","summary":"Create API token","description":"Creates a new API token for the account with the given name and resource permissions.","tags":["API Tokens"],"parameters":[{"$ref":"#/components/parameters/account_id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiTokenRequest"}}}},"responses":{"200":{"description":"Created API token (includes full token value once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTokenWithToken"}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"}}}}}}
```

## Get API token

> Returns a single API token by id.

```json
{"openapi":"3.1.0","info":{"title":"Account Management","version":"2.0.0"},"tags":[{"name":"API Tokens"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"account_id":{"description":"Unique account ID","name":"account_id","in":"path","required":true,"schema":{"type":"integer","format":"int64","minimum":1}},"api_token_id":{"description":"API token ID","name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}},"schemas":{"ApiToken":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"API token ID"},"name":{"type":"string","description":"Token display name"},"last_4_digits":{"type":"string","description":"Last 4 characters of the token (full token is only shown on create or reset)"},"created_by":{"type":"string","description":"Name of the user or token that created this token"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the token expires (ISO 8601); null if the token does not expire"},"resources":{"type":"array","description":"Permissions granted to this token","items":{"$ref":"#/components/schemas/ResourcePermission"}}}},"ResourcePermission":{"type":"object","properties":{"resource_type":{"type":"string","enum":["account","project","inbox","sending_domain"],"description":"Resource type for this permission"},"resource_id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Resource identifier"},"access_level":{"type":"integer","enum":[10,100],"description":"10 = viewer, 100 = admin."}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"NOT_FOUND":{"description":"Returns not found error message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}}},"paths":{"/api/accounts/{account_id}/api_tokens/{id}":{"get":{"operationId":"getApiToken","summary":"Get API token","description":"Returns a single API token by id.","tags":["API Tokens"],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/api_token_id"}],"responses":{"200":{"description":"API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiToken"}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"404":{"$ref":"#/components/responses/NOT_FOUND"}}}}}}
```

## Delete API token

> Permanently deletes an API token.

```json
{"openapi":"3.1.0","info":{"title":"Account Management","version":"2.0.0"},"tags":[{"name":"API Tokens"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"account_id":{"description":"Unique account ID","name":"account_id","in":"path","required":true,"schema":{"type":"integer","format":"int64","minimum":1}},"api_token_id":{"description":"API token ID","name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NOT_FOUND":{"description":"Returns not found error message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}}},"schemas":{"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}}}},"paths":{"/api/accounts/{account_id}/api_tokens/{id}":{"delete":{"operationId":"deleteApiToken","summary":"Delete API token","description":"Permanently deletes an API token.","tags":["API Tokens"],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/api_token_id"}],"responses":{"204":{"description":"Token deleted (no body)"},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"404":{"$ref":"#/components/responses/NOT_FOUND"}}}}}}
```

## Reset API token

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

```json
{"openapi":"3.1.0","info":{"title":"Account Management","version":"2.0.0"},"tags":[{"name":"API Tokens"}],"servers":[{"description":"Mailtrap API","url":"https://mailtrap.io"}],"security":[{"HeaderAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"HeaderAuth":{"type":"apiKey","description":"Pass the API token in the Api-Token","in":"header","name":"Api-Token"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"account_id":{"description":"Unique account ID","name":"account_id","in":"path","required":true,"schema":{"type":"integer","format":"int64","minimum":1}},"api_token_id":{"description":"API token ID","name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}},"schemas":{"ApiTokenWithToken":{"type":"object","properties":{"id":{"type":"integer","format":"int64","description":"API token ID"},"name":{"type":"string","description":"Token display name"},"last_4_digits":{"type":"string","description":"Last 4 characters of the token (full token is only shown on create or reset)"},"created_by":{"type":"string","description":"Name of the user or token that created this token"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"When the token expires (ISO 8601); null if the token does not expire"},"resources":{"type":"array","description":"Permissions granted to this token","items":{"$ref":"#/components/schemas/ResourcePermission"}},"token":{"type":"string","description":"Full token value (only returned on create or reset; store securely)"}}},"ResourcePermission":{"type":"object","properties":{"resource_type":{"type":"string","enum":["account","project","inbox","sending_domain"],"description":"Resource type for this permission"},"resource_id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Resource identifier"},"access_level":{"type":"integer","enum":[10,100],"description":"10 = viewer, 100 = admin."}}},"UnauthenticatedResponse":{"title":"UnauthenticatedResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"PermissionsDeniedResponse":{"title":"PermissionsDeniedResponse","type":"object","properties":{"errors":{"type":"string","description":"Error message"}}},"NotFoundResponse":{"title":"NotFoundResponse","type":"object","properties":{"error":{"type":"string","description":"Error message"}}},"UnprocessableEntity":{"title":"UnprocessableEntity","type":"object","properties":{"errors":{"type":"object","description":"Validation errors per attribute. Entire record errors are under `base` key."}}}},"responses":{"UNAUTHENTICATED":{"description":"Returns unauthorized error message. Check your credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"PERMISSION_DENIED":{"description":"Returns forbidden error message. Check your permissions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PermissionsDeniedResponse"}}}},"NOT_FOUND":{"description":"Returns not found error message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundResponse"}}}},"UNPROCESSABLE_ENTITY":{"description":"Validation error or other business rule violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntity"}}}}}},"paths":{"/api/accounts/{account_id}/api_tokens/{id}/reset":{"post":{"operationId":"resetApiToken","summary":"Reset API token","description":"Expires the requested token and creates a new token with the same permissions.\nThe old token stops working after a short grace period. The response includes\nthe new token value (store it securely; it is only returned once).\nOnly tokens that have not already been reset (no expiration set) can be reset.\n","tags":["API Tokens"],"parameters":[{"$ref":"#/components/parameters/account_id"},{"$ref":"#/components/parameters/api_token_id"}],"responses":{"200":{"description":"New API token (includes full token value once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiTokenWithToken"}}}},"401":{"$ref":"#/components/responses/UNAUTHENTICATED"},"403":{"$ref":"#/components/responses/PERMISSION_DENIED"},"404":{"$ref":"#/components/responses/NOT_FOUND"},"422":{"$ref":"#/components/responses/UNPROCESSABLE_ENTITY"}}}}}}
```