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.
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.
/api/v2/api-keysList API keys
Authentication: User
Query parameters
| Field | Type | Description |
|---|---|---|
page | integer | Page number, starting from 1 |
page_size | integer | Items per page |
sort | string | Sort fields, comma-separated; prefix `-` for descending, e.g. `-created_at,id` |
/api/v2/api-keysCreate API key
Authentication: User
Request body application/json
| Field | Type | Description |
|---|---|---|
allow_ips | ApiKeyAllowIps | Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials |
expires_at | string | Expires at |
nameRequired | string | Name |
password | string | The caller's current login password; give this, totp_code, or both to re-authenticate. |
scopesRequired | string[] | Granted scopes, same values as scopes at creation |
totp_code | string | The caller's current 6-digit TOTP code; the account must have TOTP enabled. |
/api/v2/api-keys/{id}Update API key IP allowlist or reset it
Authentication: User
Request body application/json
| Field | Type | Description |
|---|---|---|
allow_ips | ApiKeyAllowIps | Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials |
password | string | The caller's current login password; give this, totp_code, or both to re-authenticate. |
reset | boolean | When true, issue a new key; the old one stops working at once |
totp_code | string | The caller's current 6-digit TOTP code; the account must have TOTP enabled. |
/api/v2/api-keys/{id}Delete API key
Authentication: User
API keys object
| Field | Type | Description |
|---|---|---|
allow_ips | ApiKeyAllowIps | Caller IP allowlist (single IPs only, at most 200); empty means no restriction. Calls from other IPs get 401 as invalid credentials |
created_at | string | Created at |
expires_at | string | Expires at |
id | integer | Record ID |
last_used_at | string | Time of last use; null if never used |
name | string | Name |
password | string | The caller's current login password; give this, totp_code, or both to re-authenticate. |
prefix | string | First few characters of the plaintext key, for recognition |
reset | boolean | When true, issue a new key; the old one stops working at once |
scopes | string[] | Granted scopes, same values as scopes at creation |
secret | string | Plaintext key (the X-API-Key value), returned only once at creation; only a hash is stored |
totp_code | string | The caller's current 6-digit TOTP code; the account must have TOTP enabled. |
updated_at | string | Updated at |
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.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"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"
}