Tokens
Personal access token management operations.
/tokens
Create a personal access token
Issues a personal access token for the authenticated user and returns the plaintext bearer
token once, in the response's token attribute. It is never retrievable again, so
capture it on receipt.
The token's scopes and lifetime (1_month, 6_months, or 12_months) are fixed at
creation; it can call only the endpoints its granted scopes permit. Use it as
Authorization: Bearer <token> on every subsequent request.
Requires the tokens:write scope.
Request body
application/vnd.api+json
— CreateTokenRequestDocument
|
Attribute
|
Type
|
Description
|
|---|---|---|
name
required
|
string | |
scopes
required
|
array | |
duration
required
|
string | The token's lifetime. The token stops authenticating once this period elapses — the chosen duration is enforced, not advisory. |
curl -X POST https://api.minimailer.app/tokens \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json" \ -H "Content-Type: application/vnd.api+json" \ -d '{"data":{"type":"tokens","attributes":{"name":"...","scopes":[],"duration":"..."}}}'
Responses
|
Status
|
Description
|
|---|---|
| 201 |
Personal access token created.
TokenDocument
|
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 415 |
The request Content-Type must be application/vnd.api+json, with no media type parameters other than profile (ext is rejected — no JSON:API extensions are supported — as is any other parameter such as charset).
ErrorDocument
|
| 422 |
The request document failed validation.
ValidationErrorDocument
|
| 409 |
The request conflicts with the endpoint or current state: the document's resource type does not match the endpoint, its id does not match the resource being updated, or an idempotency key was reused with a different payload. (Creating with a client-generated id and updating relationships on an endpoint that does not support them return 403 instead.)
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|
/tokens/{token}
Revoke a personal access token
Permanently revokes one of the authenticated user's personal access tokens. The token stops
authenticating immediately on the next request. A token that does not exist or belongs to
another user returns 404 rather than revealing its existence.
Requires the tokens:write scope.
Parameters
|
Name
|
In
|
Description
|
|---|---|---|
token
required
|
path | The token identifier. |
curl -X DELETE https://api.minimailer.app/tokens/{token} \ -H "Authorization: Bearer $MINIMAILER_API_TOKEN" \ -H "Accept: application/vnd.api+json"
Responses
|
Status
|
Description
|
|---|---|
| 204 | Personal access token revoked. |
| 401 |
Authentication is required.
ErrorDocument
|
| 403 |
The authenticated token does not have permission to perform this action.
ErrorDocument
|
| 404 |
The requested resource could not be found.
ErrorDocument
|
| 406 |
The Accept header mentions the JSON:API media type only in instances modified by disallowed media type parameters (or only with unsupported ext extensions), so no acceptable representation remains.
ErrorDocument
|
| 429 |
The caller exceeded the API rate limit.
ErrorDocument
|