Authentication
Toda chamada a /v1/* é autenticada por API Key, enviada como Bearer token:
curl https://api.gateway.example/v1/payments/pay_123 \
-H "Authorization: Bearer sk_test_..."
Formato da chave
sk_test_...— chave de sandbox.sk_live_...— chave de produção.
O prefixo é só cosmético (identifica visualmente o ambiente no Backoffice) — a validação real é sempre pelo hash da chave inteira. Uma chave nunca é reexibida depois de criada; se perdida, revogue-a e gere outra.
Escopo: tenant vs. merchant
Uma chave é criada dentro de um merchant específico e carrega esse escopo — toda chamada fica
automaticamente restrita àquele tenantId/merchantId, sem precisar (nem poder) informá-los
no corpo da request para sobrescrever.
Nota
Se sua plataforma opera múltiplos merchants sob o mesmo tenant (ex.: um marketplace), fale com quem administra sua instância sobre uma chave escopada ao tenant — nesse caso
merchantId passa a ser obrigatório no corpo de endpoints como POST /v1/payments.Revogação
Backoffice → Merchants → API Keys → Revogar. Uma chave revogada passa a responder
401 UNAUTHORIZED imediatamente — sem propagação assíncrona, sem cache.
Erros de autenticação
| Situação | Status | error.code |
|---|---|---|
Header Authorization ausente | 401 | UNAUTHORIZED |
| Chave inválida ou revogada | 401 | UNAUTHORIZED |
Ver Errors pro envelope completo.