Chaves de API e escopos
Cada chave é de uma empresa e de um ambiente, e tem um nível de acesso por recurso. A chave completa aparece uma única vez; a plataforma guarda só o hash.
Formato e envio
A chave começa com sk_test_ (ambiente de teste) ou sk_live_ (produção), seguida de 43 caracteres. Mande em toda chamada no cabeçalho Authorization: Bearer sk_…; o cabeçalho X-API-Key: sk_… também é aceito.
Para conferir uma chave sem mexer em nada, chame GET /v1/account: não exige escopo e mostra a empresa, o ambiente e os escopos.
Chave só no servidor. Nunca no navegador, no app do celular nem no git.
Criar, vencer e revogar
- No painel, em Desenvolvedores › Chaves de API. Quem cria: Proprietário, Administrador ou Desenvolvedor, com o código do app autenticador.
- A chave de produção só é criada depois que o cadastro da empresa é aprovado.
- Validade de 90 dias, 365 dias ou sem vencimento, escolhida na criação.
- Até 20 chaves ativas por ambiente.
- Escopos e lista de IPs não mudam depois de criada: para mudar, crie outra chave, troque no seu servidor e revogue a antiga (revogar também pede o código do app autenticador).
- Perdeu a chave? Ela não aparece de novo: revogue e crie outra.
Escopos
Cada recurso tem um nível: none, read ou write. write inclui read. Chave criada antes de um recurso existir fica com none nele: ela não ganha acesso novo sozinha.
| Recurso | O que cobre | read | write |
|---|---|---|---|
charges | Cobranças, devoluções e links de pagamento | GET /v1/charges, /v1/refunds e /v1/payment-links | Criar e cancelar cobrança, devolver, criar e alterar link |
payouts | Pagamentos e destinos | GET /v1/payouts, /v1/beneficiaries e /v1/settlement-accounts | Pedir e cancelar pagamento, salvar e arquivar beneficiário |
balance | Saldos | GET /v1/balances | Nenhuma rota de escrita |
disputes | Disputas (MED) | GET /v1/disputes e /v1/charges/:id/disputes | Evidência, defesa e explicação |
webhooks | Eventos dos webhooks | GET /v1/events e /v1/events/:id | Nenhuma rota de escrita (endpoints só no painel) |
customers | Clientes | GET /v1/customers e /v1/customers/:id | Nenhuma rota de escrita |
O cadastro de endpoints de webhook continua só no painel: pela API, o escopo webhooks lê os eventos já emitidos.
Erros de autenticação
| Código | HTTP | Quando acontece |
|---|---|---|
API_KEY_INVALID | 401 | Chave ausente, fora do formato, desconhecida, revogada ou vencida. |
API_KEY_SCOPE | 403 | A chave não tem o nível pedido pela rota no recurso. |
IP_NOT_ALLOWED | 403 | A chave tem lista de IPs e a chamada veio de outro. |
MERCHANT_NOT_ACTIVE | 403 | Chave sk_live_ de empresa que ainda não está ativa. Use o ambiente de teste. |
MERCHANT_SUSPENDED | 403 | A empresa está suspensa: a API recusa as chamadas. |
MERCHANT_BLOCKED | 403 | A empresa está bloqueada: a API recusa as chamadas. |
RATE_LIMITED | 429 | Mais de 1.200 chamadas por minuto com a mesma chave. |
Lista de IPs em Lista de IPs.