PT EN

Programadores

URL base: $CONSUMER_API

O objecto

dataarray of string · opcional

Listar âmbitos disponíveis para chaves pessoais

Registos

GET /developer/scopes

Returns, sorted and without duplicates, the account permissions the caller holds across the active memberships of every account linked to them (for example invoice.read or payment.create). These are the only scopes a personal API key may carry, and a secret key created now would carry exactly this list. An account holder whose membership lists no explicit permissions counts as holding account.read, invoice.read, payment.create, reading.create, ticket.create, connection.manage and member.invite. Only a signed-in consumer identity may call it; any other principal type receives 403.

Devolve

200 Scopes a personal API key may carry

Mostrar atributos
dataarray of string · opcional

Erros 401 · 403

curl -X GET "$CONSUMER_API/developer/scopes" \
  -H "Authorization: Bearer sk_test_..."
Resposta 200
{
  "data": [
    "data"
  ]
}

Listar chaves de API pessoais

Registos

GET /developer/api-keys

Returns the personal API keys the caller owns, one cursor page at a time. Keys belong to the person, not to an account or utility. Each key is identified by prefix and last four characters with its computed status (active, expired or revoked); the secret is never returned again. Only a consumer identity may call it, and the call may be made with a personal API key; any other principal type receives 403.

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 Personal 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

curl -X GET "$CONSUMER_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 pessoal

Registos

POST /developer/api-keys

Create a personal API key; the full key appears once in the response

Issues a personal API key that acts as the caller on the consumer API and returns its full secret only in this response. Scopes are account permissions, not staff scopes: a secret key (no scopes given) carries every account permission the caller holds now, and a restricted key needs at least one scope, each of which the caller must hold on at least one linked account (see the scopes call). Personal keys are live only: mode test returns 400. Every time the key is used, the server checks that its owner still holds every scope on it and refuses the key otherwise. Each consumer operation needs one scope from a key (reads of accounts, readings and requests need account.read; bills, payments and debt need invoice.read; paying needs payment.create; submitting readings needs reading.create; tickets, invoice disputes and leak allowance applications need ticket.create; connection and service work needs connection.manage; delegates need member.invite), and a key without it gets 403. Changes to the person's relationships, account links, account memberships, profile, inbox and keys refuse every key with 403 and code api_key_not_allowed. The request must come from the person, not from an API key (403 with code api_key_not_allowed). A missing or over-long name (128 characters), a past expires_at, an invalid allowed_ips entry, scopes on a secret key or a restricted key without scopes return 400; a scope the caller does not hold returns 403. The creation is written to the audit trail.

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

curl -X POST "$CONSUMER_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 pessoal

Registos

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

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

Issues a replacement for one of the caller's personal keys 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. Unlike staff keys, rolling does not re-check the key's scopes against what the caller holds now; the check made each time a key is used still applies. The request must come from the person, not from an API key. An unknown key returns 404. The roll is written to the audit trail.

Parâmetros

idstring · caminho · obrigatório

Identifier of the caller's active personal API key to replace.

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 · 404 · 409

curl -X POST "$CONSUMER_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 pessoal

Registos

DELETE /developer/api-keys/{id}

Ends one of the caller's personal keys at once, so requests made with it fail from now on, and writes an audit record. Revoking a key that is already revoked succeeds. The request must come from the person, not from an API key. An unknown key returns 404.

Parâmetros

idstring · caminho · obrigatório

Identifier of the caller's personal API key to revoke.

Devolve

204 Revoked

Erros 401 · 403 · 404

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

Revoked