Personal Access Tokens

Personal Access Token (PAT) management. PATs are long-lived, scoped bearer tokens (format: ck_pat_<40 hex chars>) intended for programmatic integrations, automation scripts, CI pipelines, and agentic workflows. Unlike standard JWTs they carry an explicit scope list and can optionally be restricted to a subset of account IDs (allowed_account_ids), enabling the principle of least privilege. Lifecycle: create a PAT via POST /users/self/pats — the full token is returned once and must be stored securely. Use it as Authorization: Bearer ck_pat_... on any supported endpoint. Revoke it via DELETE /users/self/pats/{id} when it is no longer needed. Security best practices: request only the scopes your integration actually needs; set an expires_at for tokens used in ephemeral environments; store the plaintext token in a secret manager, not in source code; rotate PATs periodically and revoke any that may have been exposed.

[Beta] List Personal Access Tokens

GET

https://api.cakemail.dev

/users/self/pats

List the authenticated user's Personal Access Tokens with pagination.

Required scope(s): tokens:read

[Beta] List Personal Access Tokens › query Parameters

page

integer · min: 1

Default: 1

per_page

integer · min: 1 · max: 100

Default: 50

status

string · enum

An enumeration.

Enum values:

active

revoked

expired

all

Default: active

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] List Personal Access Tokens › Responses

Successful Response

PatListResponse

PatResponse[] · required

PatPagination · required

[Beta] Create a Personal Access Token

POST

https://api.cakemail.dev

/users/self/pats

Creates a new Personal Access Token (PAT) for the authenticated user.

A PAT is a long-lived, scoped bearer token (format: ck_pat_<40 hex chars>) intended for programmatic and agentic integrations — scripts, CI pipelines, third-party tools, and AI agents — where storing a username and password is undesirable.

Unlike a standard JWT obtained via POST /token, a PAT:

carries an explicit list of granted scopes (least-privilege access control)
can optionally be restricted to specific account IDs via allowed_account_ids
does not expire by default, but can be given a hard expires_at deadline
can be revoked individually via DELETE /users/self/pats/{id} without affecting login

The full token plaintext is returned only once in the response — store it securely (e.g. in a secret manager or environment variable). It cannot be retrieved again.

Required scope(s): tokens:admin

[Beta] Create a Personal Access Token › Request Body

CreatePatRequest

name

string · minLength: 1 · maxLength: 128 · pattern: ^[\w\s\-.,!@#%()+='\… · required

Human-readable token name

scopes

PatScopeInput[] · required

Requested scopes (broad or granular)

Enum values:

lists:read

lists:write

lists:delete

contacts:read

contacts:write

contacts:delete

contacts:import

contacts:export

allowed_account_ids

integer[]

Restrict this token to a specific set of account IDs. When set, the token will be rejected with 403 Forbidden on any request that operates on an account not in this list, even if the owning user has access to that account. Use this to apply the principle of least privilege in multi-account contexts — for example, grant an automation token access to only the accounts it actually needs to manage. Null (default) means the token is unrestricted and inherits all account access rights of the owning user.

expires_at

integer

Expiry as a Unix timestamp (seconds since epoch). Null = never expires.

[Beta] Create a Personal Access Token › Responses

Successful Response

CreatePatResponse

key_prefix

string · required

Public identifier (first 12 chars of token)

name

string · required

Human-readable token name

scopes

string[] · required

Granted granular scopes

status

string · required

Token status: active or revoked

created_at

integer · required

Creation timestamp (Unix)

plaintext

string · required

Full token plaintext (shown once; store securely)

allowed_account_ids

integer[]

Null = unrestricted. List = restricted to these account IDs.

expires_at

integer

Expiry timestamp (Unix) or null

revoked_at

integer

Revocation timestamp (Unix) or null

[Beta] List another user's Personal Access Tokens

GET

https://api.cakemail.dev

/users/{user_id}/pats

List Personal Access Tokens for a specific user. Requires admin access.

Required scope(s): tokens:admin

[Beta] List another user's Personal Access Tokens › path Parameters

user_id

integer · required

Target user ID

[Beta] List another user's Personal Access Tokens › query Parameters

page

integer · min: 1

Default: 1

per_page

integer · min: 1 · max: 100

Default: 50

status

string · enum

An enumeration.

Enum values:

active

revoked

expired

all

Default: active

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] List another user's Personal Access Tokens › Responses

Successful Response

PatListResponse

PatResponse[] · required

PatPagination · required

[Beta] Get PAT audit log (self)

GET

https://api.cakemail.dev

/users/self/pats/logs

Returns a paginated audit trail of PAT lifecycle events for the authenticated user.

Required scope(s): tokens:read

[Beta] Get PAT audit log (self) › query Parameters

key_prefix

string

Filter by token key prefix

action

string

Filter by action: create, update, or revoke

page

integer · min: 1

Page number

Default: 1

per_page

integer · min: 1 · max: 100

Results per page (max 100)

Default: 50

start_time

integer · min: 1 · max: 2147483647

Filter from timestamp (Unix epoch)

end_time

integer · min: 1 · max: 2147483647

Filter to timestamp (Unix epoch)

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Get PAT audit log (self) › Responses

Successful Response

PatAuditLogResponse

PatAuditLogEntry[] · required

PatPagination · required

[Beta] Get PAT audit log (admin)

GET

https://api.cakemail.dev

/users/{user_id}/pats/logs

Returns a paginated audit trail of PAT lifecycle events for a specific user.

Required scope(s): tokens:admin

[Beta] Get PAT audit log (admin) › path Parameters

user_id

integer · required

Target user ID

[Beta] Get PAT audit log (admin) › query Parameters

key_prefix

string

Filter by token key prefix

action

string

Filter by action: create, update, or revoke

page

integer · min: 1

Page number

Default: 1

per_page

integer · min: 1 · max: 100

Results per page (max 100)

Default: 50

start_time

integer · min: 1 · max: 2147483647

Filter from timestamp (Unix epoch)

end_time

integer · min: 1 · max: 2147483647

Filter to timestamp (Unix epoch)

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Get PAT audit log (admin) › Responses

Successful Response

PatAuditLogResponse

PatAuditLogEntry[] · required

PatPagination · required

[Beta] Get Personal Access Token metadata

GET

https://api.cakemail.dev

/users/self/pats/{key_prefix}

Get metadata for a specific Personal Access Token by its key prefix.

Required scope(s): tokens:read

[Beta] Get Personal Access Token metadata › path Parameters

key_prefix

string · required

Token key prefix (first 12 chars)

[Beta] Get Personal Access Token metadata › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Get Personal Access Token metadata › Responses

Successful Response

PatResponse

key_prefix

string · required

Public identifier (first 12 chars of token)

name

string · required

Human-readable token name

scopes

string[] · required

Granted granular scopes

status

string · required

Token status: active or revoked

created_at

integer · required

Creation timestamp (Unix)

allowed_account_ids

integer[]

Null = unrestricted. List = restricted to these account IDs.

expires_at

integer

Expiry timestamp (Unix) or null

revoked_at

integer

Revocation timestamp (Unix) or null

[Beta] Update a Personal Access Token

PATCH

https://api.cakemail.dev

/users/self/pats/{key_prefix}

Update the name, scopes, or allowed account IDs of a PAT. Cannot update your own active token.

Required scope(s): tokens:admin

[Beta] Update a Personal Access Token › path Parameters

key_prefix

string · required

Token key prefix

[Beta] Update a Personal Access Token › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Update a Personal Access Token › Request Body

UpdatePatRequest

name

string · minLength: 1 · maxLength: 128 · pattern: ^[\w\s\-.,!@#%()+='\…

scopes

PatScopeInput[]

New scope list (granular)

Enum values:

lists:read

lists:write

lists:delete

contacts:read

contacts:write

contacts:delete

contacts:import

contacts:export

allowed_account_ids

integer[]

[Beta] Update a Personal Access Token › Responses

Successful Response

PatResponse

key_prefix

string · required

Public identifier (first 12 chars of token)

name

string · required

Human-readable token name

scopes

string[] · required

Granted granular scopes

status

string · required

Token status: active or revoked

created_at

integer · required

Creation timestamp (Unix)

allowed_account_ids

integer[]

Null = unrestricted. List = restricted to these account IDs.

expires_at

integer

Expiry timestamp (Unix) or null

revoked_at

integer

Revocation timestamp (Unix) or null

[Beta] Revoke a Personal Access Token

DELETE

https://api.cakemail.dev

/users/self/pats/{key_prefix}

Soft-revoke a Personal Access Token. Cannot revoke your own active token.

Required scope(s): tokens:admin

[Beta] Revoke a Personal Access Token › path Parameters

key_prefix

string · required

Token key prefix

[Beta] Revoke a Personal Access Token › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Revoke a Personal Access Token › Responses

Successful Response

PatResponse

key_prefix

string · required

Public identifier (first 12 chars of token)

name

string · required

Human-readable token name

scopes

string[] · required

Granted granular scopes

status

string · required

Token status: active or revoked

created_at

integer · required

Creation timestamp (Unix)

allowed_account_ids

integer[]

Null = unrestricted. List = restricted to these account IDs.

expires_at

integer

Expiry timestamp (Unix) or null

revoked_at

integer

Revocation timestamp (Unix) or null

[Beta] Get another user's Personal Access Token metadata

GET

https://api.cakemail.dev

/users/{user_id}/pats/{key_prefix}

Get metadata for a specific Personal Access Token belonging to another user. Requires admin access.

Required scope(s): tokens:admin

[Beta] Get another user's Personal Access Token metadata › path Parameters

user_id

integer · required

Target user ID

key_prefix

string · required

Token key prefix (first 12 chars)

[Beta] Get another user's Personal Access Token metadata › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Get another user's Personal Access Token metadata › Responses

Successful Response

PatResponse

key_prefix

string · required

Public identifier (first 12 chars of token)

name

string · required

Human-readable token name

scopes

string[] · required

Granted granular scopes

status

string · required

Token status: active or revoked

created_at

integer · required

Creation timestamp (Unix)

allowed_account_ids

integer[]

Null = unrestricted. List = restricted to these account IDs.

expires_at

integer

Expiry timestamp (Unix) or null

revoked_at

integer

Revocation timestamp (Unix) or null

[Beta] Revoke another user's Personal Access Token

DELETE

https://api.cakemail.dev

/users/{user_id}/pats/{key_prefix}

Soft-revoke a Personal Access Token belonging to another user. Requires admin access.

Required scope(s): tokens:admin

[Beta] Revoke another user's Personal Access Token › path Parameters

user_id

integer · required

Target user ID

key_prefix

string · required

Token key prefix

[Beta] Revoke another user's Personal Access Token › query Parameters

account_id

integer · min: 1

Optional Account ID to be used for the request

[Beta] Revoke another user's Personal Access Token › Responses

Successful Response

PatResponse

key_prefix

string · required

Public identifier (first 12 chars of token)

name

string · required

Human-readable token name

scopes

string[] · required

Granted granular scopes

status

string · required

Token status: active or revoked

created_at

integer · required

Creation timestamp (Unix)

allowed_account_ids

integer[]

Null = unrestricted. List = restricted to these account IDs.

expires_at

integer

Expiry timestamp (Unix) or null

revoked_at

integer

Revocation timestamp (Unix) or null

Token Account