Autenticação

Chaves de API

Gere suas chaves no painel, em Chaves de API. Toda chave tem o prefixo ax_ e é enviada no cabeçalho Authorization. A conta precisa estar ativa e com a verificação de identidade aprovada para operar em produção.

Authorization: Bearer ax_4f8c2a9e1b7d3056a8c4e2f9b1d7a305

Onde a chave pode ficar

A chave é um segredo de servidor. Nunca a coloque em aplicativo mobile, front-end, repositório público ou variável com prefixo NEXT_PUBLIC_. Quem tem a chave pode criar cobranças e consultar seu saldo em seu nome.

Com o escopo payouts:write, a chave autentica o pedido de saque. O envio ao PIX pode ser imediato ou passar por análise da plataforma, conforme a configuração vigente da conta. Proteja a chave — quem a possui pode solicitar saques em seu nome.

Escopos

Cada chave carrega escopos que limitam o que ela faz. Conceda o mínimo necessário:

• charges:write — criar e cancelar cobranças.
• charges:read — consultar cobranças e o extrato.
• payouts:write — solicitar saques.
• balance:read — consultar saldo.

Rotação

Você pode manter várias chaves ativas ao mesmo tempo. Para rotacionar sem indisponibilidade: crie a nova chave, publique nos seus serviços, confirme que o tráfego migrou e só então revogue a antiga. A revogação é imediata e irreversível.

Falha de autenticação

Chave ausente, malformada ou revogada retorna 401. Chave válida sem o escopo necessário retorna 403.

{
  "error": {
    "type": "unauthorized",
    "code": "invalid_api_key",
    "message": "Chave de API inválida ou revogada."
  }
}

Limite de requisições

O limite padrão é de 100 requisições por minuto por chave. Ao estourar, a resposta é 429 com o cabeçalho Retry-After em segundos. Veja Convenções para a estratégia de retentativa recomendada.