Tokens
Personal access token management operations.
POST
/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. |
POST /tokens
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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
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. Branch on the error code: conflict — 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; agent_category_conflict — the agent_id names an identity already bound to the other kind of mail (one agent identity sends either transactional or marketing mail, never both; an identity dormant for 30 days may rebind). (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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|
DELETE
/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. |
DELETE /tokens/{token}
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 token lacks the scope this operation requires (error code missing_scope), or the request breaks a JSON:API protocol rule (client_generated_id, unsupported_relationship_update). Never returned for a record that belongs to another account — that case is a 404.
ErrorDocument
|
| 404 |
The resource does not exist, or it belongs to another account. The two cases return the same status, error code and detail by design, so the error document does not confirm that an identifier is in use.
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 request was rate limited. Branch on the error code: rate_limited means the account exceeded its API rate limit, and agent_throttled means the agent named by agent_id has a restricted sender reputation and has exhausted the send allowance for its tier.
ErrorDocument
|