Autenticação

A API pública da Allya Payments usa API keys no header Authorization. Não há OAuth, JWT ou sessão por cookie em rotas /v1.

Header obrigatório

Authorization: Bearer sk_test_...

• Bearer é a palavra-chave padrão (RFC 6750): não troque por outra.
• Use sk_test_… para sandbox e sk_live_… para production.
• O ambiente é inferido do prefixo da chave: você não passa environmentId no body.

const response = await fetch("https://payments-api.allyasolutions.com/v1/auth/test", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.ALLYA_API_KEY}`,
  },
});

const data = await response.json();

Testar uma chave antes de qualquer outra coisa

Use GET /v1/auth/test como primeiro ping ao integrar uma chave nova ou ao mudar de ambiente. Ele:

• Confirma que o Bearer chega bem montado.
• Devolve a qual organização, projeto e ambiente a chave pertence.
• Não consome rate limit de pagamentos nem chama nenhum gateway externo.
• Tem custo desprezível: pode ser usado em healthcheck do seu serviço.

const response = await fetch("https://payments-api.allyasolutions.com/v1/auth/test", {
  headers: {
    Authorization: `Bearer ${process.env.ALLYA_API_KEY}`,
  },
});

if (!response.ok) {
  throw new Error("API key inválida");
}

const context = await response.json();
console.log(context.environment.kind); // "sandbox" ou "production"

Resposta esperada:

{
  "ok": true,
  "organization": { "id": "org_c17b9e0d4a2f4c68b7d3e9a015f6c2b4" },
  "project": { "id": "prj_8b2e1d9c4f6a4c3d9012ab7e5f8c0631" },
  "environment": { "id": "env_2f6c0a9d8e3b4f17a5c1d209b6e8f432", "kind": "sandbox" },
  "apiKey": { "id": "key_a6b4c2d9e1f04a73b8c6d5e2f9013a7c" }
}

Em scripts de deploy, rodar auth/test antes de tocar em pagamentos evita descobrir uma chave revogada apenas quando uma cobrança real falha.

Quando vier 401

Lista de verificação antes de abrir investigação:

1. Header presente? Faça console.log(req.headers.authorization) no seu cliente e confirme que existe.
2. Formato correto? Bearer sk_test_xxx: com espaço único entre Bearer e a chave. Sem aspas, sem ponto-e-vírgula.
3. Chave colada inteira? O prefixo sk_test_ ou sk_live_ precisa estar lá. Truncamento em copy-paste é comum.
4. Chave revogada? No painel, em API Keys, chaves revogadas mostram badge revogada: não autenticam mais.
5. Chave do ambiente errado? Uma sk_test_… em uma rota de produção da sua aplicação retorna 401 porque o ambiente não bate com o esperado, ou autentica em sandbox por engano. Confira o environment.kind em auth/test.
6. Ambiente da instância correto? Se você operar múltiplas instâncias da Allya (ex.: staging e prod), confira que está apontando para o domínio certo.

Se nenhum dos seis explica, abra o painel e regenere a chave.

Onde NÃO usar a API key

• ❌ Frontend / código que roda no navegador: a chave fica visível, qualquer um copia. Sempre proxy via seu próprio backend.
• ❌ Query string (?apiKey=...): apareceria em logs de proxy, CDN e analytics.
• ❌ Repositório git: mesmo privado, eleva o risco. Use .env.local (ignorado) ou secret manager.
• ❌ Print de tela / screenshot em documentação interna: quem manda o ticket pode esquecer de borrar.
• ❌ Logs sem mascaramento: adicione filtro no seu logger para zerar headers Authorization.

Para CI/CD, use secret manager nativo (Vercel Env, Railway Variables, GitHub Actions secrets).

Múltiplas chaves no mesmo ambiente

É possível ter mais de uma sk_test_ (ou sk_live_) ativa simultaneamente no mesmo projeto/ambiente. Recomendado para:

• Separação por serviço: uma chave por aplicação consumidora (backend principal, worker de jobs, integração com terceiro). Se vazar, você revoga só uma.
• Rotação sem downtime: crie a nova, deploy nas aplicações, revogue a antiga.

Veja API Keys para o fluxo completo de criação e revogação.

Erros comuns

Veja também

• API Keys: gerar, mascarar, revogar e rotacionar.
• Ambientes: como sandbox e production isolam dados.
• Rate limiting: cotas e headers de retorno.
• Erros: referência completa de códigos.