API Keys

API keys autenticam chamadas na API pública da Allya Payments.

Cada API key pertence a um projeto e a um ambiente específico.

Prefixos

sk_test_...  # sandbox
sk_live_...  # production

Gerar API key

No painel:

1. Entre no projeto.
2. Selecione o ambiente no switcher.
3. Acesse API Keys.
4. Crie uma nova chave com um nome descritivo.
5. Copie a chave completa no momento da criação.

A chave completa é exibida apenas uma vez. Depois disso, o painel mostra apenas a versão mascarada.

Armazenamento seguro

A Allya não salva a API key em texto puro. O banco armazena apenas:

• hash da chave;
• prefixo;
• versão mascarada;
• datas de criação, último uso e revogação.

Usar em chamadas

const allyaApiKey = process.env.ALLYA_API_KEY;

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

Revogar API key

No painel, use o botão Revogar na lista de chaves.

Chaves revogadas não autenticam novas chamadas, mas continuam no histórico técnico para auditoria.

Boas práticas

• Use uma chave por aplicação ou serviço: facilita revogação sem afetar todo mundo.
• Use sk_test_ em desenvolvimento.
• Use sk_live_ somente em produção.
• Nunca salve API keys no frontend.
• Nunca envie API keys em query string.
• Rotacione chaves quando um membro deixa o time ou quando suspeitar de exposição.

Rotação sem downtime

Para trocar uma chave em uso sem janela de indisponibilidade:

1. Gere a nova no painel (mesmo ambiente).
2. Deploy a nova chave em todas as aplicações que consomem a API. Confirme via GET /v1/auth/test que cada aplicação está usando a nova.
3. Revogue a antiga.

A Allya não tem expiração automática nem janela de "grace period": as duas chaves convivem até você revogar a antiga. Use isso a seu favor: deploy primeiro, revogue depois.

Veja também

• Autenticação: uso da chave em chamadas e GET /v1/auth/test.
• Ambientes: relação entre prefixo e ambiente.
• Indo para produção: momento certo para gerar sk_live_.