API keys api-keys

API keys of the current user. The plaintext key is returned only once at creation, and scopes can be limited per domain.

Pick an endpoint to see its example call on the right.

User accountsAuthentication: User4 endpoints

Authentication

Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.

X-API-Key

Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).

Conventions

Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.

Times are RFC 3339 (UTC); amounts are in cents.

Writes return 200/201/204 on success; duplicates of a unique key return 409.

GET/api/v2/api-keysList API keys

Authentication: User

Query parameters

FieldTypeDescription
pageinteger Page number, starting from 1
Default 1
page_sizeinteger Items per page
Default 20
sortstring Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id`
POST/api/v2/api-keysCreate API key

Authentication: User

Request body application/json

FieldTypeDescription
allow_ipsApiKeyAllowIps Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials
expires_atstring Expires at
nameRequiredstring Name
passwordstring The caller's current login password; give this, totp_code, or both to re-authenticate.
scopesRequiredstring[] Granted scopes, same values as scopes at creation
totp_codestring The caller's current 6-digit TOTP code; the account must have TOTP enabled.
PUT/api/v2/api-keys/{id}Update API key IP allowlist or reset it

Authentication: User

Request body application/json

FieldTypeDescription
allow_ipsApiKeyAllowIps Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials
passwordstring The caller's current login password; give this, totp_code, or both to re-authenticate.
resetboolean When true, issue a new key; the old one stops working at once
totp_codestring The caller's current 6-digit TOTP code; the account must have TOTP enabled.

API keys object

FieldTypeDescription
allow_ipsApiKeyAllowIps Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials
created_atstring Created at
read-only
expires_atstring Expires at
idinteger Record ID
read-only
last_used_atstring Time of last use; null if never used
namestring Name
passwordstring The caller's current login password; give this, totp_code, or both to re-authenticate.
prefixstring First few characters of the plaintext key, for recognition
resetboolean When true, issue a new key; the old one stops working at once
scopesstring[] Granted scopes, same values as scopes at creation
secretstring Plaintext key (the X-API-Key value), returned only once at creation; only a hash is stored
totp_codestring The caller's current 6-digit TOTP code; the account must have TOTP enabled.
updated_atstring Updated at
read-only

Responses and errors

Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "code": "validation_failed",
  "detail": "Invalid request parameters",
  "errors": [
    {
      "code": "required",
      "field": "/name",
      "message": "name is required"
    }
  ],
  "request_id": "0123456789abcdef",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "about:blank"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command