Chaves de API do Merchant

Esses endpoints alimentam a tela de chaves de API do Tokeflow Dashboard para um Merchant: listar as chaves existentes, gerar uma nova, consultar quais escopos ela pode carregar e revogar uma chave que não deve mais funcionar. As chaves que eles gerenciam são as mesmas credenciais sk_… (secreta) e pk_… (pública) que sua integração apresenta à API pública — o Dashboard é simplesmente a forma amigável de gerenciá-las.

Chaves secretas concedem acesso do lado do servidor e pertencem a um gerenciador de segredos; chaves públicas são seguras para uso no cliente e restritas ao 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.

Como funciona o fluxo da tela de chaves

O endpoint de escopos alimenta o formulário de criação de chaves: ele retorna apenas os escopos válidos para este Merchant e o tipo de chave escolhido, de modo que o usuário nunca pode selecionar um escopo que a chave não poderia carregar. Após a criação, a chave completa nunca é exibida novamente — a lista identifica cada chave apenas pelo seu key_prefix.

O objeto de chave de API

Retornado na criação; o endpoint de listagem retorna o mesmo objeto sem o segredo api_key, exclusivo da criação.

Endpoints

GET/api/v1/merchant/api-keys

Retorna uma lista paginada das chaves de API do Merchant — o Merchant é obtido a partir do header x-merchant-id.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchant/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-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"
    },
    {
      "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"
    }
  ],
  "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. A chave completa nunca é incluída aqui; cada chave é identificada pelo seu key_prefix, que não é secreto.

POST/api/v1/merchant/api-keys

Cria uma chave de API para o Merchant identificado por x-merchant-id. A resposta é o único lugar em que a chave completa (api_key) é retornada.

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchant/api-keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  -H "Content-Type: application/json" \
  -d '{
    "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/merchant/api-keys/scopes

Retorna os escopos que podem ser atribuídos às chaves de API deste Merchant. Escopos exclusivos de Organization são excluídos. Filtre por key_type para obter os escopos válidos para chaves públicas ou secretas — é isso que o formulário de criação de chaves do Dashboard usa para popular seu seletor de escopos antes de chamar POST /merchant/api-keys.

Parâmetros de consulta

Exemplo de requisição

curl -G https://api.tokeflow.com/api/v1/merchant/api-keys/scopes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9" \
  --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": [
    "transactions:*",
    "customers:*"
  ]
}

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 esta entidade e tipo de chave — 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.

DELETE/api/v1/merchant/api-keys/:id

Revoga uma chave de API permanentemente. A revogação entra em vigor imediatamente: qualquer requisição que apresentar a chave revogada falha na autenticação a partir desse momento. Não há como desfazer — se a carga de trabalho ainda precisar de acesso, crie uma chave substituta primeiro.

Parâmetros de caminho

Exemplo de requisição

curl -X DELETE https://api.tokeflow.com/api/v1/merchant/api-keys/ak_9f2e6c81 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "x-merchant-id: mrc_8a3f12d9"

Exemplo de resposta — 204 No Content

O corpo da resposta está vazio.

Erros

Os casos mais comuns para estes endpoints:

Consulte Erros para o formato geral de erro usado em toda a API.

Relacionados

• Chaves de API (API pública) — gerencie chaves de forma programática a partir do seu backend, incluindo pausar/reativar.
• 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.
• Erros — o envelope de erro padrão.