Cakemail API

Token

Endpointhttps://api.cakemail.dev

Standard token management (OAuth 2.0). Use these endpoints to obtain short-lived JWT access and refresh tokens via the Resource Owner Password Credentials grant, refresh expired tokens, and complete multi-factor authentication challenges. These tokens are intended for interactive sessions and first-party UI use. For programmatic or agentic integrations, see Personal Access Tokens.

deprecated

Refresh a token

PUT

https://api.cakemail.dev

/token

This endpoint is deprecated. Please see the "Create or Refresh a Token" endpoint instead.

Refresh a token › query Parameters

version

string · enum

An enumeration.

Enum values:

Default: v1

Refresh a token › Request Body

refresh_token

string · required

grant_type

string · enum

An enumeration.

Enum values:

refresh_token

expiration_seconds

integer · min: 600

Refresh a token › Responses

Successful Response

access_token

string · required

Bearer token for authenticating API requests

token_type

string · required

Token type, always "bearer"

expires_in

integer · required

Token lifetime in seconds

refresh_token

string · required

Token used to obtain a new access token when the current one expires

accounts

integer[] · unique · required

Set of account IDs the authenticated user has access to

PUT/token

curl --request PUT \
  --url https://api.cakemail.dev/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data refresh_token=refresh_token \
  --data expiration_seconds=0

shell

Example Request Body

{
  "grant_type": "refresh_token",
  "refresh_token": "refresh_token",
  "expiration_seconds": 0
}

json

Example Responses

{
  "access_token": "access_token",
  "token_type": "token_type",
  "expires_in": 0,
  "refresh_token": "refresh_token",
  "accounts": [
    0
  ]
}

json

application/json

Create or Refresh a standard token (JWT)

POST

https://api.cakemail.dev

/token

Standard Token (JWT) — Authentication

This endpoint issues short-lived JSON Web Tokens (JWTs) using the OAuth 2.0 Resource Owner Password Credentials grant. These tokens are intended for interactive sessions and first-party UI integrations where a human user supplies their credentials at login time.

For programmatic, automated, or agentic integrations, use Personal Access Tokens (PATs) instead — see POST /users/self/pats. PATs are long-lived, carry explicit scopes, and do not require storing a username and password.

The response includes a short-lived access token (JWT) and a refresh token. Access and refresh tokens are sensitive data and must be stored securely.

Creating a token

When the grant_type is set to password, the endpoint will authenticate the user using the provided username and password. If the user is authenticated successfully, the endpoint will generate an access token and a refresh token.

The access token is used to authenticate requests to other endpoints, while the refresh token is used to obtain a new access token when the current one expires.

The refresh token is a long-lived token that can be used to obtain a new access token when the current one expires. Refresh tokens cannot be used as access tokens.

Multi-Factor Authentication

If the user account is protected by multi-factor authentication (MFA), the endpoint will respond with a 401 Unauthorized status and include a challenge field in the response body. This field contains a unique identifier. To complete the token creation, the client must complete the challenge by sending a request to the /token/challenge endpoint.

Refreshing a token

When the grant_type is set to refresh_token, the endpoint will refresh the access token using the provided refresh token.

Create or Refresh a standard token (JWT) › query Parameters

version

string · enum

An enumeration.

Enum values:

Default: v2

Create or Refresh a standard token (JWT) › Request Body

grant_type

string · enum

An enumeration.

Enum values:

password

refresh_token

username

string · email

password

string · maxLength: 128

account_id

integer

scopes

string · pattern: ^(user|admin|interna…

A comma separated list of scopes.

Default: user

expiration_seconds

integer · min: 600

refresh_token

string

Create or Refresh a standard token (JWT) › Responses

Successful Response

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: access_token, token_type, expires_in +2 more
	type = object · requires: challenge

Properties for TokenResponse:

access_token

string · required

Bearer token for authenticating API requests

token_type

string · required

Token type, always "bearer"

expires_in

integer · required

Token lifetime in seconds

refresh_token

string · required

Token used to obtain a new access token when the current one expires

accounts

integer[] · unique · required

Set of account IDs the authenticated user has access to

POST/token

curl --request POST \
  --url https://api.cakemail.dev/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=password \
  --data username=test@example.com \
  --data password=password \
  --data account_id=0 \
  --data scopes=scopes \
  --data expiration_seconds=0 \
  --data refresh_token=refresh_token

shell

Example Request Body

{
  "grant_type": "password",
  "username": "test@example.com",
  "password": "password",
  "account_id": 0,
  "scopes": "scopes",
  "expiration_seconds": 0,
  "refresh_token": "refresh_token"
}

json

Example Responses

{
  "access_token": "access_token",
  "token_type": "token_type",
  "expires_in": 0,
  "refresh_token": "refresh_token",
  "accounts": [
    0
  ]
}

json

application/json

Complete a Multi-Factor Authentication challenge

POST

https://api.cakemail.dev

/token/challenge

This endpoint serves to complete the MFA (multi-factor authentication) challenge and return an access and refresh token pair. The complete login sequence for an MFA-enabled user is as follows:

The client sends a POST request to /token with the username and password in the request body.
The API returns a challenge in the response body.
The client sends a POST request to /token/challenge with the challenge and code in the request body.
The API returns an access_token and refresh_token in the response body.

Access and Refresh tokens should be treated as sensitive data and should be stored securely.

Complete a Multi-Factor Authentication challenge › Request Body

challenge

string · required

required

scopes

string[] · unique

Enum values:

user

admin

internal

auth

email_api

Default: ["user"]

expiration_seconds

integer · min: 600

Complete a Multi-Factor Authentication challenge › Responses

Successful Response

access_token

string · required

Bearer token for authenticating API requests

token_type

string · required

Token type, always "bearer"

expires_in

integer · required

Token lifetime in seconds

refresh_token

string · required

Token used to obtain a new access token when the current one expires

accounts

integer[] · unique · required

Set of account IDs the authenticated user has access to

POST/token/challenge

curl --request POST \
  --url https://api.cakemail.dev/token/challenge \
  --header 'Content-Type: application/json' \
  --data '
{
  "challenge": "challenge",
  "code": "string",
  "scopes": [
    "user"
  ],
  "expiration_seconds": 0
}
'

shell

Example Request Body

{
  "challenge": "challenge",
  "code": "string",
  "scopes": [
    "user"
  ],
  "expiration_seconds": 0
}

json

Example Responses

{
  "access_token": "access_token",
  "token_type": "token_type",
  "expires_in": 0,
  "refresh_token": "refresh_token",
  "accounts": [
    0
  ]
}

json

application/json

Personal Access Tokens

Refresh a token

PUT

https://api.cakemail.dev

/token

This endpoint is deprecated. Please see the "Create or Refresh a Token" endpoint instead.

Refresh a token › query Parameters

version

string · enum

An enumeration.

Enum values:

Default: v1

Refresh a token › Request Body

refresh_token

string · required

grant_type

string · enum

An enumeration.

Enum values:

refresh_token

expiration_seconds

integer · min: 600

Refresh a token › Responses

Successful Response

access_token

string · required

Bearer token for authenticating API requests

token_type

string · required

Token type, always "bearer"

expires_in

integer · required

Token lifetime in seconds

refresh_token

string · required

Token used to obtain a new access token when the current one expires

accounts

integer[] · unique · required

Set of account IDs the authenticated user has access to

Create or Refresh a standard token (JWT)

POST

https://api.cakemail.dev

/token

Standard Token (JWT) — Authentication

The response includes a short-lived access token (JWT) and a refresh token. Access and refresh tokens are sensitive data and must be stored securely.

Creating a token

The access token is used to authenticate requests to other endpoints, while the refresh token is used to obtain a new access token when the current one expires.

The refresh token is a long-lived token that can be used to obtain a new access token when the current one expires. Refresh tokens cannot be used as access tokens.

Multi-Factor Authentication

Refreshing a token

When the grant_type is set to refresh_token, the endpoint will refresh the access token using the provided refresh token.

Create or Refresh a standard token (JWT) › query Parameters

version

string · enum

An enumeration.

Enum values:

Default: v2

Create or Refresh a standard token (JWT) › Request Body

grant_type

string · enum

An enumeration.

Enum values:

password

refresh_token

username

string · email

password

string · maxLength: 128

account_id

integer

scopes

string · pattern: ^(user|admin|interna…

A comma separated list of scopes.

Default: user

expiration_seconds

integer · min: 600

refresh_token

string

Create or Refresh a standard token (JWT) › Responses

Successful Response

anyOf

At least one variant must match. Multiple variants may match simultaneously.

Decision Table

Variant	Matching Criteria
	type = object · requires: access_token, token_type, expires_in +2 more
	type = object · requires: challenge

Properties for TokenResponse:

access_token

string · required

Bearer token for authenticating API requests

token_type

string · required

Token type, always "bearer"

expires_in

integer · required

Token lifetime in seconds

refresh_token

string · required

Token used to obtain a new access token when the current one expires

accounts

integer[] · unique · required

Set of account IDs the authenticated user has access to

curl --request POST \ --url https://api.cakemail.dev/token \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data grant_type=password \ --data username=test@example.com \ --data password=password \ --data account_id=0 \ --data scopes=scopes \ --data expiration_seconds=0 \ --data refresh_token=refresh_token

Complete a Multi-Factor Authentication challenge

POST

https://api.cakemail.dev

/token/challenge

This endpoint serves to complete the MFA (multi-factor authentication) challenge and return an access and refresh token pair. The complete login sequence for an MFA-enabled user is as follows:

The client sends a POST request to /token with the username and password in the request body.
The API returns a challenge in the response body.
The client sends a POST request to /token/challenge with the challenge and code in the request body.
The API returns an access_token and refresh_token in the response body.

Access and Refresh tokens should be treated as sensitive data and should be stored securely.

Complete a Multi-Factor Authentication challenge › Request Body

challenge

string · required

required

scopes

string[] · unique

Enum values:

user

admin

internal

auth

email_api

Default: ["user"]

expiration_seconds

integer · min: 600

Complete a Multi-Factor Authentication challenge › Responses

Successful Response

access_token

string · required

Bearer token for authenticating API requests

token_type

string · required

Token type, always "bearer"

expires_in

integer · required

Token lifetime in seconds

refresh_token

string · required

Token used to obtain a new access token when the current one expires

accounts

integer[] · unique · required

Set of account IDs the authenticated user has access to