# Escopos

Cada credencial recebe um conjunto de **escopos** que define o que ela pode fazer. Cada endpoint exige um escopo específico; o token só consegue executar a operação se a credencial tiver o escopo correspondente. O princípio é o de menor privilégio: peça apenas o que a sua integração precisa.

| Escopo | Permite |
|---|---|
| `account:read` | Listar e detalhar contas, consultar saldo, consultar limites e consultar a trilha de eventos da conta |
| `account:write` | Abrir conta adicional, alterar limites, bloquear, desbloquear e encerrar conta |
| `statement:read` | Consultar extrato e obter comprovante |
| `fee:read` | Consultar o catálogo de tarifas e as tarifas cobradas |
| `pix:read` | Consultar chaves DICT, consultar chave externa, status de PIX, trilha de devoluções, status de cobrança, status de portabilidade e consultar e listar intervenções MED e infrações DICT |
| `pix:write` | Registrar e excluir chave DICT, enviar e devolver PIX, criar cobrança imediata e com vencimento, decodificar BR Code, reivindicar portabilidade de chave, operar intervenções MED (abrir, cancelar, devolução dos fundos) e infrações DICT (relato, cancelamento, defesa) |
| `transfer:read` | Status de transferência, listar TED recebidas e listar favoritos |
| `transfer:write` | Enviar TED, transferência interna, devolver TED recebida e criar ou excluir favorito |
| `customer:create` | Cadastrar cliente |
| `customer:read` | Consultar cliente |
| `webhook:read` | Listar e detalhar webhooks e ler o catálogo de eventos |
| `webhook:write` | Registrar, atualizar, excluir, rotacionar segredo, testar e reenviar webhooks |

O escopo concedido no token é a interseção dos escopos solicitados com as permissões da credencial. Se uma chamada exigir um escopo que a credencial não possui, a resposta é `403`, indicando a permissão necessária.

## Conjunto completo de escopos

A tabela acima lista os escopos exigidos pelos endpoints atuais do catálogo `/api/partner/v1`. Uma credencial com acesso total carrega o conjunto: `pix:read`, `pix:write`, `account:read`, `account:write`, `transfer:read`, `transfer:write`, `statement:read`, `fee:read`, `customer:create`, `customer:read`, `webhook:read` e `webhook:write`.