Autenticação e escopos

Autenticação

Todos os endpoints utilizam autenticação via API Key enviada no header x-api-key. Para maior segurança, você pode configurar domínios e IPs permitidos na página de Integração, restringindo de onde suas requisições podem ser feitas.

Escopos da API Key

Ao criar uma API Key, você pode restringi-la a funcionalidades específicas (escopos). Por exemplo, uma chave usada apenas para receber pagamentos pode ter acesso somente a PIX_IN e CHECKOUT.

Escopo	Acesso liberado
`PIX_IN`	Cobranças PIX (criar, consultar, efetivar homologação)
`PIX_OUT`	Saques PIX (criar, consultar)
`BOLETO`	Cobranças por boleto (emitir, consultar, cancelar, segunda via, efetivar homologação)
`CHECKOUT`	Links de pagamento / checkout (criar, consultar)
`WALLET`	Consulta de saldo da carteira
`PRODUCTS`	Catálogo de produtos (criar, listar, consultar, atualizar)
`WEBHOOKS`	Endpoints de webhook (criar, listar, atualizar, remover, rotacionar a credencial), entregas e reenvio

Se nenhum escopo for selecionado, a chave tem acesso total a todas as funcionalidades. Chaves criadas antes desta funcionalidade continuam com acesso total (retrocompatível).

Os escopos são por funcionalidade, não por leitura ou escrita: quem consulta saques (PIX_OUT) também pode criá-los. Só WALLET é apenas leitura. Para uma integração ou um agente de IA que não deve sacar, não inclua PIX_OUT.

Uma requisição feita com uma chave que não possui o escopo necessário retorna HTTP 403.

Formato das Respostas

Todas as respostas seguem um formato padrão. Sucesso:

{
  "message": "Mensagem descritiva",
  "response": { ... }
}

Erro:

{
  "response": null,
  "errors": ["Descrição do erro"]
}

​Autenticação

​Escopos da API Key

​Formato das Respostas

Autenticação

Escopos da API Key

Formato das Respostas