List API keys
Returns API keys for the active organization. Plaintext keys are NOT returned; only metadata (id, prefix, scopes, expiry, last-used).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List API keys › Responses
OK
Create an API key
Mints a new API key. The plaintext token (sk_live_... or sk_test_...) is returned ONCE in the response and never persisted; record it immediately.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create an API key › Request Body
nameHuman-readable label for the key, shown in the dashboard list. Leading and trailing whitespace is trimmed.
scopesPermissions the key carries, e.g. "customer.read". Must name at least one scope: an empty list is NOT shorthand for all-access, and a key with no scopes can reach no endpoint. To grant broad access, pass the explicit list. GET /v1/permissions returns the catalog; every scope must also be held by the caller minting the key.
allowed_ipsIP addresses or CIDR blocks permitted to present this key. Omit or pass an empty list to leave the key unrestricted.
expires_atMoment the key stops authenticating. Omit for a non-expiring key.
key_typeKey environment: "sk_live" or "sk_test". Omit to inherit the workspace mode (sandbox workspaces mint sk_test, live workspaces mint sk_live).
Create an API key › Responses
Created
Rotate an API key
Issues a fresh plaintext token for the org's key, atomically revoking the old one after a 24h grace window. Use to roll keys without losing scopes/IP allowlists/expiry settings. The new token is returned once.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Rotate an API key › Responses
Created
Revoke an API key
Marks an API key as revoked. Subsequent requests presenting this key will fail with 401.
path Parameters
idAPI key ID (UUID)
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Revoke an API key › Responses
OK