Chaves de API

Toda requisição à API da Tokeflow se autentica com uma chave de API — uma credencial vinculada a exatamente uma entidade (uma Organization ou um de seus Merchants) e a uma lista explícita de escopos. Os endpoints desta página gerenciam essas chaves programaticamente: crie uma chave com escopos de privilégio mínimo, liste as existentes, pause uma chave temporariamente e revogue-a definitivamente. Tudo o que o Dashboard da Tokeflow faz com chaves, seu backend pode automatizar — útil para fluxos de onboarding que geram uma chave por Merchant, e para rotação programada de credenciais.

As chaves existem em dois tipos. As chaves secretas (sk_…) concedem acesso do lado do servidor e são enviadas no cabeçalho Authorization: Bearer; as chaves públicas (pk_…) são seguras para uso no cliente e restritas aos escopos que o Bridge SDK precisa no navegador. Consulte Autenticação para o modelo completo, e Ambientes e chaves de API para saber como as chaves codificam ambiente e entidade em seu prefixo.

Ciclo de vida e rotação da chave

Ao rotacionar, sempre crie e implante a chave substituta antes de revogar a antiga — a revogação entra em vigor imediatamente, e qualquer serviço que ainda estiver usando a chave antiga passa a receber 401 authentication_error.

O objeto de chave de API

Retornado por todos os endpoints desta página. A resposta de criação também traz api_key — o segredo completo — apenas uma vez.

Endpoints

GET/api/v1/api-keys

Retorna uma lista paginada de chaves de API. Organizations podem filtrar por entity_type e entity_id para visualizar as chaves de um Merchant específico.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  --data-urlencode "entity_type=merchant" \
  --data-urlencode "entity_id=mrc_8a3f12d9" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

Exemplo de resposta — 200 OK

{
  "data": [
    {
      "id": "ak_9f2e6c81",
      "entity_type": "merchant",
      "entity_id": "mrc_8a3f12d9",
      "name": "Checkout service (production)",
      "key_prefix": "sk_live_mer_7d21",
      "scopes": ["transactions:read", "transactions:write"],
      "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
      "is_active": true,
      "expires_at": null,
      "last_used_at": "2026-08-11T18:22:04.000Z",
      "created_at": "2026-03-02T09:15:00.000Z",
      "key_hash": "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"
    },
    {
      "id": "ak_5b0d3a47",
      "entity_type": "merchant",
      "entity_id": "mrc_8a3f12d9",
      "name": "Storefront widget",
      "key_prefix": "pk_live_mer_0c1d",
      "scopes": ["tokens:read"],
      "allowed_ips": null,
      "is_active": false,
      "expires_at": "2026-12-31T23:59:59.000Z",
      "last_used_at": "2026-07-30T10:41:52.000Z",
      "created_at": "2026-01-20T16:00:00.000Z",
      "key_hash": "3c363836cf4e16666669a25da280a1865c2d2874"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

data contém as chaves da página atual e meta os metadados de paginação — avance page enquanto has_next for true. Consulte Paginação e filtragem para o padrão geral.

POST/api/v1/api-keys

Cria uma chave de API para uma Organization ou Merchant. A resposta é o único lugar em que a chave completa (api_key) é retornada.

Campos da requisição

Códigos de resposta

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/api-keys \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "merchant",
    "entity_id": "mrc_8a3f12d9",
    "name": "Checkout service (production)",
    "scopes": ["transactions:read", "transactions:write"],
    "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
    "key_type": "secret"
  }'

Exemplo de resposta — 201 Created

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": true,
  "expires_at": null,
  "last_used_at": null,
  "created_at": "2026-08-12T14:03:00.000Z",
  "api_key": "sk_live_mer_7d21c39ab8e4f560",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

GET/api/v1/api-keys/scopes

Retorna todos os escopos válidos que podem ser atribuídos a chaves de API. Filtre por entity_type (organization/merchant) e/ou key_type (secret/public) para restringir os resultados ao que uma determinada chave poderia realmente carregar — útil para validar uma lista de scopes antes de chamar POST /api-keys, ou para construir um formulário de criação de chaves.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/api-keys/scopes \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  --data-urlencode "entity_type=organization" \
  --data-urlencode "key_type=secret"

Exemplo de resposta — 200 OK (truncado)

{
  "scopes": [
    {
      "scope": "transactions:read",
      "description": "List and view transactions"
    },
    {
      "scope": "transactions:write",
      "description": "Create, capture, and refund transactions"
    },
    {
      "scope": "customers:read",
      "description": "List and view customers"
    }
  ],
  "wildcards": [
    "org:*",
    "org:transactions:*"
  ]
}

Cada item em scopes associa a string do escopo a uma descrição legível por humanos. wildcards lista as strings de escopo curinga válidas para a entidade/tipo de chave solicitada — um curinga concede todos os escopos que ele cobre, portanto reserve-os para serviços confiáveis e rigorosamente controlados, e prefira listas explícitas de escopos em todos os outros casos.

PATCH/api/v1/api-keys/:id

Atualiza o estado de ativação de uma chave. Defina is_active como false para desativar a chave — requisições que a usarem passam a falhar imediatamente com 401 authentication_error — ou de volta para true para reativá-la. Use isto como a alternância reversível; use revogação quando a chave nunca deva voltar.

Campos da requisição

Exemplo de requisição

curl -X PATCH https://api.tokeflow.com/api/v1/api-keys/ak_9f2e6c81 \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Exemplo de resposta — 200 OK

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": false,
  "expires_at": null,
  "last_used_at": "2026-08-11T18:22:04.000Z",
  "created_at": "2026-08-12T14:03:00.000Z",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

Um 403 é retornado se a chave existir mas não pertencer à sua entidade, e um 404 se ela não existir.

POST/api/v1/api-keys/:id/revoke

Revoga uma chave de API, desativando-a permanentemente. A revogação entra em vigor imediatamente: qualquer requisição que apresentar a chave revogada falha com 401 authentication_error. Diferentemente de uma desativação via PATCH, uma chave revogada é aposentada definitivamente — se a carga de trabalho ainda precisar de acesso, crie uma chave substituta primeiro.

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/api-keys/ak_9f2e6c81/revoke \
  -H "Authorization: Bearer sk_live_org_2b7e91c4a0f53d68"

Exemplo de resposta — 200 OK

{
  "id": "ak_9f2e6c81",
  "entity_type": "merchant",
  "entity_id": "mrc_8a3f12d9",
  "name": "Checkout service (production)",
  "key_prefix": "sk_live_mer_7d21",
  "scopes": ["transactions:read", "transactions:write"],
  "allowed_ips": ["203.0.113.10", "198.51.100.0/24"],
  "is_active": false,
  "expires_at": null,
  "last_used_at": "2026-08-11T18:22:04.000Z",
  "created_at": "2026-08-12T14:03:00.000Z",
  "key_hash": "6dcd4ce23d88e2ee9568ba546c007c63d9131c1b"
}

Um 403 é retornado se a chave não pertencer à sua entidade, e um 404 se ela não existir.

Erros

Os erros usam o envelope padrão. Os casos mais comuns para este recurso:

Consulte Erros para o envelope completo e o catálogo de tipos.

Relacionados

• Autenticação — o esquema Bearer, escopos e a anatomia da chave.
• Ambientes e chaves de API — ciclo de vida da chave, armazenamento e práticas de rotação.
• Paginação e filtragem — convenções de listagem usadas pelo endpoint de listagem.
• Erros — o envelope de erro padrão.