Escopos de Permissão

Para máxima segurança da sua operação financeira, a KavroPay permite restringir as ações de cada chave de API através de Escopos de Permissão (API Scopes).

Princípio do Menor Privilégio: Chaves utilizadas em integrações de e-commerce ou bots de vendas devem ter apenas permissões de leitura e criação de cobranças, impedindo que requisições comprometidas consigam realizar saques ou transferências.

Escopos Disponíveis

Escopo	Descrição	Casos de Uso Recomendados
`payments:write`	Permite emitir novas cobranças PIX e links de pagamento.	Checkout do e-commerce, bots de vendas, PDV físico.
`payments:read`	Permite consultar status de cobranças, clientes cadastrados, histórico e saldo da conta.	Telas de consulta de pedidos, relatórios financeiros internos.
`withdrawals:write`	Permite criar solicitações de transferência/saque PIX para contas externas.	Sistemas de split financeiro, payouts automáticos de afiliados.
`withdrawals:read`	Permite consultar o histórico e o status de liquidação de saques solicitados.	Conciliação contábil e auditoria financeira.

Matriz de Acesso por Endpoint

Método	Endpoint	Escopo Exigido
`POST`	`/v1/charges`	`payments:write`
`POST`	`/v1/payments`	`payments:write`
`GET`	`/v1/charges/{id}`	`payments:read`
`GET`	`/v1/charges`	`payments:read`
`GET`	`/v1/status`	`payments:read`
`POST`	`/v1/status`	`payments:read`
`GET`	`/v1/balance`	`payments:read`
`POST`	`/v1/customers`	`payments:write`
`GET`	`/v1/customers`	`payments:read`
`GET`	`/v1/customers/{id}`	`payments:read`
`POST`	`/v1/withdrawals`	`withdrawals:write`
`GET`	`/v1/withdrawals/{id}`	`withdrawals:read`
`GET`	`/v1/withdrawals`	`withdrawals:read`

Erro de Escopo Insuficiente (HTTP 403 Forbidden)

Se sua aplicação tentar executar uma operação sem o escopo correspondente (por exemplo, tentar realizar um saque com uma chave contendo apenas payments:write), o servidor recusará a chamada imediatamente:

{
  "statusCode": 403,
  "message": "Insufficient scope: requires withdrawals:write",
  "error": "Forbidden",
  "timestamp": "2026-09-28T12:00:00.000Z",
  "path": "/v1/withdrawals"
}

Para alterar ou adicionar escopos a uma chave existente, acesse o painel em Configurações > Chaves de API ou gere uma nova chave específica para o serviço desejado.

Autenticação

Cabeçalhos e padrões de autenticação

Formato de Valores & Metadata

Como formatar valores decimais e enviar metadados

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Escopos de Permissão

Escopos Disponíveis

Matriz de Acesso por Endpoint

Erro de Escopo Insuficiente (HTTP 403 Forbidden)

Autenticação

Formato de Valores & Metadata