Developer: Api keys

Base URL: $BUSINESS_API

List API keys by prefix and last four

Logs

GET /developer/api-keys

Returns the API keys that belong to the caller's context (the tenant, or the organization when no tenant is selected), one cursor page at a time. Keys are identified by prefix and last four characters; the secret is never returned again. Each key reports its computed status (for example active, expired or revoked). Requires developer:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 API keys

Show attributes
dataarray of DeveloperApiKey · optional
Show child attributes
idstring · required
namestring · required
kindstring · required

one of secret, restricted

modestring · required

one of live, test

prefixstring · required

Leading characters shown in listings

last_fourstring · required
scopesarray of string · required
statusstring · required

one of active, expired, revoked

created_bystring · required
created_atstring (date-time) · required
last_used_atstring (date-time) · optional
expires_atstring (date-time) · optional
revoked_atstring (date-time) · optional
rolled_from_idstring · optional
rolled_to_idstring · optional
allowed_ipsarray of string · optional

IPs or CIDRs the key may be used from; empty allows any

last_used_ipstring · optional
secretstring · optional

The full key; present only on the create and roll responses. Prefixes: sk_live_, sk_test_, sk_rlive_, sk_rtest_

has_moreboolean · optional
next_cursorstring · optional

Errors 400 · 401 · 403

Permissions developer:read · Roles: admin, owner

curl -X GET "$BUSINESS_API/developer/api-keys" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "dev_2R5wU9D4kFDEuJVeYfxoK79EmHn",
      "name": "Ana Matsinhe",
      "kind": "secret",
      "mode": "live",
      "prefix": "sk_live_ab12",
      "last_four": "last four",
      "scopes": [
        "scope"
      ],
      "status": "active",
      "created_by": "created by",
      "created_at": "2026-11-19T09:30:00Z",
      "last_used_at": "2026-11-19T09:30:00Z",
      "expires_at": "2026-11-19T09:30:00Z",
      "revoked_at": "2026-11-19T09:30:00Z",
      "rolled_from_id": "rol_2t9WqfdsKVPYOb7QyPDqy1bSQfD",
      "rolled_to_id": "rol_2wwXNOid16AhFeCFr2g7xCKL1Wc",
      "allowed_ips": [
        "allowed ip"
      ],
      "last_used_ip": "last used ip",
      "secret": "secret"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a secret or restricted API key

Logs

POST /developer/api-keys

Create a secret or restricted API key; the full key appears once in the response

Issues a key in the caller's context and returns its full secret only in this response. A secret key (no scopes given) receives every grantable scope the caller holds; a restricted key needs at least one scope, and every scope must be in the catalog and held by the caller. Mode defaults to live: test keys are issued only in a sandbox tenant, a sandbox issues only test keys, and test keys cannot hold money-moving write scopes outside a sandbox. The request must come from a person, not an API key, and needs developer:write; a missing or over-long name (128 characters), an unknown scope, a past expires_at or a mode mismatch returns 400, and a scope the caller lacks returns 403.

Body application/json

namestring · required
kindstring · optional

Defaults to restricted when scopes are given and secret otherwise

one of secret, restricted

modestring · optional · default live

one of live, test

scopesarray of string · optional

Required for a restricted key; must be held by the caller

expires_atstring (date-time) · optional
allowed_ipsarray of string · optional

Optional IPs or CIDRs the key may be used from

Returns

201 Key created; secret is shown only here

Show attributes
idstring · required
namestring · required
kindstring · required

one of secret, restricted

modestring · required

one of live, test

prefixstring · required

Leading characters shown in listings

last_fourstring · required
scopesarray of string · required
statusstring · required

one of active, expired, revoked

created_bystring · required
created_atstring (date-time) · required
last_used_atstring (date-time) · optional
expires_atstring (date-time) · optional
revoked_atstring (date-time) · optional
rolled_from_idstring · optional
rolled_to_idstring · optional
allowed_ipsarray of string · optional

IPs or CIDRs the key may be used from; empty allows any

last_used_ipstring · optional
secretstring · optional

The full key; present only on the create and roll responses. Prefixes: sk_live_, sk_test_, sk_rlive_, sk_rtest_

Errors 400 · 401 · 403

Permissions developer:write · Roles: admin, owner

curl -X POST "$BUSINESS_API/developer/api-keys" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "kind": "secret",
  "mode": "live",
  "scopes": [
    "scope"
  ],
  "expires_at": "2026-11-19T09:30:00Z",
  "allowed_ips": [
    "allowed ip"
  ]
}'
Response 201
{
  "id": "dev_2R5wU9D4kFDEuJVeYfxoK79EmHn",
  "name": "Ana Matsinhe",
  "kind": "secret",
  "mode": "live",
  "prefix": "sk_live_ab12",
  "last_four": "last four",
  "scopes": [
    "scope"
  ],
  "status": "active",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "last_used_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "revoked_at": "2026-11-19T09:30:00Z",
  "rolled_from_id": "rol_2t9WqfdsKVPYOb7QyPDqy1bSQfD",
  "rolled_to_id": "rol_2wwXNOid16AhFeCFr2g7xCKL1Wc",
  "allowed_ips": [
    "allowed ip"
  ],
  "last_used_ip": "last used ip",
  "secret": "secret"
}

Replace a key, keeping the old one valid for the overlap

Logs

POST /developer/api-keys/{id}/roll

Issues a replacement key with the same name, kind, mode, scopes, allowed IPs and expiry, returns its secret once, and keeps the old key valid for overlap_seconds (default 24 hours, maximum 7 days, never past the old key's own expiry). Only an active key that has not already been rolled can be rolled; otherwise the response is 409. The request must come from a person, needs developer:write, and the caller must hold every scope the key carries, or the response is 403.

Parameters

idstring · path · required

Identifier of the active API key to replace, in the caller's context.

Body application/json

overlap_secondsinteger · optional

How long the old key or secret keeps working; default 86400

Returns

201 Replacement key; secret is shown only here

Show attributes
idstring · required
namestring · required
kindstring · required

one of secret, restricted

modestring · required

one of live, test

prefixstring · required

Leading characters shown in listings

last_fourstring · required
scopesarray of string · required
statusstring · required

one of active, expired, revoked

created_bystring · required
created_atstring (date-time) · required
last_used_atstring (date-time) · optional
expires_atstring (date-time) · optional
revoked_atstring (date-time) · optional
rolled_from_idstring · optional
rolled_to_idstring · optional
allowed_ipsarray of string · optional

IPs or CIDRs the key may be used from; empty allows any

last_used_ipstring · optional
secretstring · optional

The full key; present only on the create and roll responses. Prefixes: sk_live_, sk_test_, sk_rlive_, sk_rtest_

Errors 400 · 401 · 403

Permissions developer:write · Roles: admin, owner

curl -X POST "$BUSINESS_API/developer/api-keys/{id}/roll" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "overlap_seconds": 0
}'
Response 201
{
  "id": "dev_2R5wU9D4kFDEuJVeYfxoK79EmHn",
  "name": "Ana Matsinhe",
  "kind": "secret",
  "mode": "live",
  "prefix": "sk_live_ab12",
  "last_four": "last four",
  "scopes": [
    "scope"
  ],
  "status": "active",
  "created_by": "created by",
  "created_at": "2026-11-19T09:30:00Z",
  "last_used_at": "2026-11-19T09:30:00Z",
  "expires_at": "2026-11-19T09:30:00Z",
  "revoked_at": "2026-11-19T09:30:00Z",
  "rolled_from_id": "rol_2t9WqfdsKVPYOb7QyPDqy1bSQfD",
  "rolled_to_id": "rol_2wwXNOid16AhFeCFr2g7xCKL1Wc",
  "allowed_ips": [
    "allowed ip"
  ],
  "last_used_ip": "last used ip",
  "secret": "secret"
}

Revoke a key immediately

Logs

DELETE /developer/api-keys/{id}

Ends the key at once, so requests made with it fail from now on, and writes an audit record. The request must come from a person, not an API key, and needs developer:write. An unknown key returns 404.

Parameters

idstring · path · required

Identifier of the API key to revoke, in the caller's context.

Returns

204 Revoked

Errors 400 · 401 · 403

Permissions developer:write · Roles: admin, owner

curl -X DELETE "$BUSINESS_API/developer/api-keys/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 204

Revoked