PT EN

Programadores: Chaves de API

URL base: $BUSINESS_API

Listar chaves de API

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

Devolve

200 API keys

Mostrar atributos
dataarray of DeveloperApiKey · opcional
Mostrar atributos filhos
idstring · obrigatório
namestring · obrigatório
kindstring · obrigatório

um de secret, restricted

modestring · obrigatório

um de live, test

prefixstring · obrigatório

Leading characters shown in listings

last_fourstring · obrigatório
scopesarray of string · obrigatório
statusstring · obrigatório

um de active, expired, revoked

created_bystring · obrigatório
created_atstring (date-time) · obrigatório
last_used_atstring (date-time) · opcional
expires_atstring (date-time) · opcional
revoked_atstring (date-time) · opcional
rolled_from_idstring · opcional
rolled_to_idstring · opcional
allowed_ipsarray of string · opcional

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

last_used_ipstring · opcional
secretstring · opcional

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

has_moreboolean · opcional
next_cursorstring · opcional

Erros 400 · 401 · 403

Permissões developer:read · Funções: admin, owner

curl -X GET "$BUSINESS_API/developer/api-keys" \
  -H "Authorization: Bearer sk_test_..."
Resposta 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"
}

Criar uma chave de API

Registos

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.

Corpo application/json

namestring · obrigatório
kindstring · opcional

Defaults to restricted when scopes are given and secret otherwise

um de secret, restricted

modestring · opcional · predefinição live

um de live, test

scopesarray of string · opcional

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

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

Optional IPs or CIDRs the key may be used from

Devolve

201 Key created; secret is shown only here

Mostrar atributos
idstring · obrigatório
namestring · obrigatório
kindstring · obrigatório

um de secret, restricted

modestring · obrigatório

um de live, test

prefixstring · obrigatório

Leading characters shown in listings

last_fourstring · obrigatório
scopesarray of string · obrigatório
statusstring · obrigatório

um de active, expired, revoked

created_bystring · obrigatório
created_atstring (date-time) · obrigatório
last_used_atstring (date-time) · opcional
expires_atstring (date-time) · opcional
revoked_atstring (date-time) · opcional
rolled_from_idstring · opcional
rolled_to_idstring · opcional
allowed_ipsarray of string · opcional

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

last_used_ipstring · opcional
secretstring · opcional

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

Erros 400 · 401 · 403

Permissões developer:write · Funções: 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"
  ]
}'
Resposta 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"
}

Renovar uma chave de API

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

overlap_secondsinteger · opcional

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

Devolve

201 Replacement key; secret is shown only here

Mostrar atributos
idstring · obrigatório
namestring · obrigatório
kindstring · obrigatório

um de secret, restricted

modestring · obrigatório

um de live, test

prefixstring · obrigatório

Leading characters shown in listings

last_fourstring · obrigatório
scopesarray of string · obrigatório
statusstring · obrigatório

um de active, expired, revoked

created_bystring · obrigatório
created_atstring (date-time) · obrigatório
last_used_atstring (date-time) · opcional
expires_atstring (date-time) · opcional
revoked_atstring (date-time) · opcional
rolled_from_idstring · opcional
rolled_to_idstring · opcional
allowed_ipsarray of string · opcional

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

last_used_ipstring · opcional
secretstring · opcional

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

Erros 400 · 401 · 403

Permissões developer:write · Funções: 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
}'
Resposta 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"
}

Revogar uma chave de API

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

204 Revoked

Erros 400 · 401 · 403

Permissões developer:write · Funções: admin, owner

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

Revoked