Escopos de API key

Cada chave de API carrega um conjunto de escopos. O escopo limita o que aquela chave pode fazer — uma chave de leitura não cria cobrança nem saque, mesmo que quem a tenha saiba o endpoint.

TODO(contrato)

Os escopos são um item portado do legado para a base Go (MIGRATION-PLAN.md §2: “Manter o par da base Go; portar os escopos do legado”). Hoje a base Go autentica pelo par pk_/sk_ mas ainda não impõe escopo por rota — a granularidade abaixo é o alvo, não o estado atual.

Pendente da frente F0 — Contrato: o conjunto final de escopos (o legado tinha quatro, e a base Go ganhou endpoints que não existiam lá — exportações, disputas, links de pagamento), o nome definitivo de cada um e o mapa escopo → rota.

Escopos herdados do legado

Escopo	Libera
charges:write	Criar cobranças, checkouts e links de pagamento
charges:read	Consultar cobranças e vendas
balance:read	Consultar saldo e extrato financeiro
webhooks:manage	Registrar, testar e remover endpoints de webhook

O conjunto padrão de uma chave nova no legado era charges:write, charges:read e balance:read — repare que webhooks:manage não entrava por padrão.

Rotas que ainda não têm escopo definido

Estas existem na API mas não têm correspondente no conjunto acima. O mapeamento depende da F0:

Rota	Escopo candidato
POST /api/withdrawals	withdrawals:write TODO(contrato)
GET /api/withdrawals	withdrawals:read TODO(contrato)
GET /api/export/charges · GET /api/export/withdrawals	exports:read TODO(contrato)

Saque merece escopo próprio

Criar cobrança e enviar dinheiro para fora são poderes muito diferentes. Uma integração que só emite cobrança nunca deveria carregar uma chave capaz de sacar — é a diferença entre um vazamento chato e um vazamento caro.

Escolhendo o conjunto mínimo

Integração	Escopos sugeridos
Loja que só cobra e confere pagamento	charges:write, charges:read
Painel interno de conciliação	charges:read, balance:read
Serviço que faz repasses automáticos	balance:read + o escopo de saque
Configuração inicial da integração	webhooks:manage, temporariamente

Prefira uma chave por integração, com o mínimo de escopos: assim uma rotação de emergência derruba só o serviço afetado.

Erro por escopo insuficiente

Quando uma chave não tem o escopo exigido pela rota, a resposta é 403. No legado a mensagem nomeava o escopo faltante — API key sem o escopo necessário: charges:write —, o que é útil no desenvolvimento e inofensivo em produção: quem já autenticou sabe qual chave usou.

Veja também

• Autenticação — como gerar e rotacionar o par de chaves.
• Códigos de erro — o significado de cada status.