Skip to main content
Todas as chamadas da API Korbit são autenticadas com uma chave de API de merchant enviada no header Authorization como bearer token.

​
Formato da chave

O secret completo só é exibido uma única vez, na criação ou rotação da chave. Guarde-o em um gerenciador de segredos — não é possível recuperá-lo depois.

​
Como enviar

Erros de autenticação retornam 401 com código INVALID_API_KEY; chaves válidas sem o escopo necessário retornam 403 com INSUFFICIENT_SCOPE. Veja Erros.

​
Ambientes

O ambiente é derivado da chave, não de um parâmetro da requisição: Uma chave test nunca funciona em produção e vice-versa: o servidor rejeita a chave se o ambiente dela não corresponde ao ambiente que está atendendo a requisição.

​
Escopos

Cada chave possui um conjunto de escopos que limita o que ela pode fazer. Aplique o princípio do menor privilégio: uma chave de Integração que só consulta pedidos não precisa de payouts:write.
Escopos de movimentação de dinheiro (payouts:write, refunds:write, iam:manage) são sensíveis: use-os apenas em chaves de serviços confiáveis, preferencialmente com IP allowlist no seu perímetro.

​
Rotação e revogação

  • Rotação (POST /v1/iam/api-keys/{id}/rotate): cria um token substituto com os mesmos escopos e revoga o anterior após um período de carência configurável (gracePeriodSeconds). Use em rotação periódica e em suspeita de vazamento.
  • Revogação (DELETE /v1/iam/api-keys/{id}): a chave morre imediatamente — todas as chamadas seguintes retornam 401.

​
Boas práticas

  1. Nunca exponha a chave no client — a chave de API é um segredo de servidor. A página de checkout do comprador não precisa dela (ele usa o link público ou tokens de sessão efêmeros).
  2. Uma chave por integração — separe chaves por serviço (ERP, e-commerce, job de conciliação) para poder revogar cada uma independentemente e auditar o uso.
  3. Rote periodicamente — por exemplo a cada 90 dias.
  4. Menor privilégio — combine escopos mínimos com o ambiente correto (test enquanto desenvolve).