Autenticação
Toda chamada autenticada envia a chave de API em um destes headers:
Authorization: Bearer SUA_CHAVE_DE_API
X-Api-Key: SUA_CHAVE_DE_API
Endpoints públicos (/health e /openapi.json) não exigem chave.
Permissões (escopos)
Cada chave carrega uma lista de permissões. Uma chamada sem a permissão necessária recebe
403 INSUFFICIENT_PERMISSIONS. Conceda o mínimo necessário.
| Permissão | Permite |
|---|---|
payments:read | Consultar pagamentos, PIX e extrato |
payments:create | Criar, cancelar e sincronizar cobranças |
customers:read | Listar e consultar clientes |
customers:create | Cadastrar clientes |
customers:update | Atualizar clientes |
withdrawals:read | Consultar saques e simular tarifas |
withdrawals:create | Solicitar saques |
webhooks:read | Consultar entregas de webhook |
webhooks:manage | Reenviar entregas de webhook |
reports:read | Relatórios e exportações |
reconciliations:read | Conciliações |
fee_rules:read | Consultar regras de tarifa |
risk:read | Consultar limites e eventos de risco |
notifications:read | Consultar notificações |
jobs:read | Consultar tarefas em segundo plano |
audit:read | Consultar trilha de auditoria |
Algumas permissões administrativas só podem ser concedidas pela própria plataforma e não aparecem na emissão de chaves.
Boas práticas
- Uma chave por integração. Assim você revoga só o que foi exposto.
- Rotacione chaves periodicamente e revogue imediatamente qualquer chave que tenha vazado.
- Nunca use a chave no front-end. O painel mostra o último uso de cada chave, o que ajuda a identificar chaves esquecidas.
- Chaves revogadas, expiradas ou inativas retornam
401com o código correspondente (API_KEY_REVOKED,API_KEY_EXPIRED,API_KEY_INACTIVE). - A API não aceita chamadas diretas de navegadores de outros domínios (sem CORS aberto): isso é intencional, para que a chave nunca precise estar no cliente.