Autenticação
Autorização por conta
O controle de acesso é feito pelo vínculo entre a sua integração e as contas que ela pode operar.
Como funciona
Cada integração é registrada e vinculada às contas que pode operar. Em toda rota /integration/v1/** que atua sobre uma conta, o gateway valida se a sua integração está vinculada à conta referenciada nos headers da request (account-id, wallet-id ou tax-identifier).
- Conta vinculada → o fluxo segue normalmente.
- Conta não vinculada →
403 forbidden. - Autorizador indisponível →
403(comportamento fail-closed, por segurança). - Header de conta ausente na request →
422 validation_error(account, wallet or tax-identifier header is required).
Parceiro com múltiplas contas
Cada conta precisa estar vinculada à integração individualmente. Uma conta nova só passa a responder depois do vínculo — até lá, todas as chamadas para ela retornam
403.Rotas que não exigem vínculo de conta
Configuração da própria integração não opera sobre conta e exige apenas um token M2M válido: /integration/v1/webhooks (POST, PUT, GET) e as rotas de notificação.
Erros relacionados
401 unauthorized— token ausente, expirado ou inválido.403 forbidden— integração não vinculada à conta referenciada nos headers, ou autorizador indisponível (fail-closed).422 validation_error— payload inválido ou header de conta ausente (account-id/wallet-id/tax-identifier).