Autenticação e permissões
API keys de integração
Envie sua API key Adila Pay em um dos cabeçalhos:
x-api-key: SUA_API_KEYAuthorization: Bearer SUA_API_KEYNas rotas financeiras, x-api-key tem precedência quando os dois cabeçalhos são enviados. Use apenas um. O backend valida expiração, organização ativa e permissões da chave.
A organização no caminho deve corresponder à organização da chave. Enviar Stripe-Account não permite escolher outra conta: o backend resolve a conta conectada a partir do vínculo autorizado.
Criação e revogação
Owner/admin podem criar API keys pelo fluxo autenticado de gestão, cuja rota é POST /v1/apikeys/. O valor completo é apresentado na criação; as consultas posteriores retornam metadados e valor mascarado. Armazene o segredo com segurança e revogue a chave quando ela deixar de ser necessária.
Permissões são negadas por padrão. Uma chave pode conceder recurso:ação, recurso:* ou *. Prefira permissões específicas para cada integração.
| Recurso | Leitura | Escrita |
|---|---|---|
| Conta e saldo | payment-account:read | Criação/onboarding exigem owner/admin com sessão |
| Clientes | customers:read | customers:write |
| Produtos e preços | products:read | products:write |
| PaymentIntents, Checkout e links de pagamento | payments:read | payments:write |
| Cupons e códigos promocionais | coupons:read | coupons:write |
| Cobranças | charges:read | Não exposta |
| Reembolsos | refunds:read | refunds:write |
| Assinaturas, faturas e portal | subscriptions:read | subscriptions:write |
| Transações de saldo | transactions:read | Não exposta |
| Repasses | payouts:read | Não exposta |
| Disputas | disputes:read | Não exposta |
| Endpoints de webhook | webhook-endpoints:read | webhook-endpoints:write |
Checkout no modo subscription exige payments:write e subscriptions:write.
O acesso total * não concede webhook-endpoints: gerenciar destinos expõe segredos de assinatura, então o escopo precisa ser concedido de forma explícita.
Sessões humanas
As rotas financeiras também aceitam sessão Better Auth. Membros podem consultar dados; viewer não pode realizar mutações financeiras. Criação de conta e geração de link de onboarding são restritas a owner/admin humanos, mesmo quando uma API key possui *.
As rotas de identidade e administração /v1 não fazem parte do SDK financeiro. Use o fluxo do dashboard para gestão de usuários, organizações, chaves e branding.
Ambientes
O prefixo da API key define o ambiente: pk_test_ opera no sandbox e pk_live_ em produção. Na sessão do painel, vale o workspace selecionado. Detalhes em Ambientes.