Aesesdocs

Autenticação

A API da Aeses usa chaves secretas para autenticar requisições. Toda requisição precisa incluir sua chave no header x-api-key. Não existe fluxo OAuth — a Aeses é uma API server-to-server, feita para ser chamada a partir do seu backend.

Enviando a chave

Requisição autenticada
curl https://api.aeses.io/v1/balances \
-H "x-api-key: sk_live_..."

Todas as requisições precisam ser feitas via HTTPS. Requisições em HTTP puro falham na terminação TLS antes mesmo de chegar à API. Requisições sem o header x-api-key, ou com chave malformada, retornam 401 authentication_error.

Formatos de chave

| Prefixo | Ambiente | Uso | | ----------- | ---------- | -------------------------------------------------------------------------------- | | sk_test_… | Modo teste | Redes públicas de testnet. Nunca movimenta fundos reais. Use em desenvolvimento. | | sk_live_… | Modo live | Redes de produção. Autoriza movimentação de valor real. |

Uma chave sk_live_ não consegue ler dados de sk_test_, e vice-versa. Os dois ambientes são totalmente isolados — veja Ambientes para detalhes.

Criar e rotacionar chaves

Gerencie suas chaves em Painel → Developers → API keys. Você pode:

  • Criar quantas chaves quiser por ambiente. Nomeie cada uma pelo sistema que a usa (ex.: checkout-prod, reconciliation-worker).
  • Rotacionar criando uma chave nova, fazendo o deploy em todos os lugares e revogando a antiga. A Aeses não força um cutover rígido — revogue quando o rollout estiver completo.
  • Revogar instantaneamente. Uma chave revogada retorna 401 authentication_error em toda requisição posterior.
Revogue chaves comprometidas imediatamente

Se uma chave secreta vazar em um log, repositório ou screenshot, revogue-a no painel na hora e substitua. Não há caminho de recuperação que não passe pela revogação.

Armazenando chaves com segurança

  • Leia a chave de uma variável de ambiente ou de um secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). Não hardcode.
  • Nunca embarque uma chave secreta em código de cliente browser, mobile ou desktop. Se um cliente precisa iniciar um pagamento, gere um objeto charge de curta duração no servidor e passe o charge ID para o cliente.
  • Evite logar a chave inteira. Se precisar logar para debug, registre só os últimos quatro caracteres.

Erros

| Status | Código | Causa | | ------ | -------------------------- | ------------------------------------------------------------ | | 401 | authentication_error | Chave ausente, malformada, revogada ou expirada. | | 401 | key_environment_mismatch | Uma chave sk_test_ foi usada contra um recurso só de live. | | 403 | forbidden | A chave é válida mas não tem permissão para este recurso. |

Veja Erros para o modelo completo de erros.