Aesesdocs

Autenticación

La API de Aeses usa claves secretas para autenticar solicitudes. Cada solicitud debe incluir tu clave en el header x-api-key. No hay flujo OAuth — Aeses es una API server-to-server, diseñada para ser llamada desde tu backend.

Enviando la clave

Solicitud autenticada
curl https://api.aeses.io/v1/balances \
-H "x-api-key: sk_live_..."

Todas las solicitudes deben enviarse por HTTPS. Las solicitudes en HTTP puro fallan en la terminación TLS antes de llegar a la API. Las solicitudes sin el header x-api-key, o con una clave mal formada, devuelven 401 authentication_error.

Formatos de clave

| Prefijo | Entorno | Uso | | ----------- | ----------- | -------------------------------------------------------------------------- | | sk_test_… | Modo prueba | Redes públicas de testnet. Nunca mueve fondos reales. Úsalo en desarrollo. | | sk_live_… | Modo live | Redes de producción. Autoriza movimientos de valor real. |

Una clave sk_live_ no puede leer datos de sk_test_, y viceversa. Los dos entornos están totalmente aislados — consulta Entornos para más detalles.

Crear y rotar claves

Gestiona tus claves desde Panel → Developers → API keys. Puedes:

  • Crear tantas claves como quieras por entorno. Nombra cada una por el sistema que la usa (p. ej. checkout-prod, reconciliation-worker).
  • Rotar creando una clave nueva, desplegándola en todos los sitios y luego revocando la antigua. Aeses no impone un corte estricto — revoca cuando tu despliegue esté completo.
  • Revocar al instante. Una clave revocada devuelve 401 authentication_error en cada solicitud posterior.
Revoca claves comprometidas de inmediato

Si una clave secreta queda expuesta en un log, repositorio o captura de pantalla, revócala desde el panel al instante y reemplázala. No hay vía de recuperación que no pase por revocar.

Almacenar claves de forma segura

  • Lee la clave desde una variable de entorno o un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager). No la hardcodees.
  • Nunca incluyas una clave secreta en código de cliente navegador, móvil o escritorio. Si un cliente necesita iniciar un pago, genera un objeto charge de corta duración en el servidor y pasa el charge ID al cliente.
  • Evita loggear la clave completa. Si necesitas loggearla para depurar, registra solo los últimos cuatro caracteres.

Errores

| Estado | Código | Causa | | ------ | -------------------------- | ----------------------------------------------------------- | | 401 | authentication_error | Clave ausente, mal formada, revocada o expirada. | | 401 | key_environment_mismatch | Se usó una clave sk_test_ contra un recurso solo de live. | | 403 | forbidden | La clave es válida pero no tiene permiso para este recurso. |

Consulta Errores para el modelo completo de errores.