Autenticación con API keys

AlchemyCode API usa llaves de API con el esquema Authorization: Bearer. Cada llave pertenece a una cuenta, tiene un entorno (live o test), un conjunto de scopes y una fecha de expiración opcional.

Cómo enviar la llave

El encabezado va en todas las peticiones a /v1, incluidas las descargas de archivos firmadas. Sin él, la API responde 401 con el código AUTH_REQUIRED.

curl -sS "https://api.434alchemycode.com/v1/me" \
  -H "Authorization: Bearer $ALCHEMY_API_KEY" \
  -H "Accept: application/json"

Formato de las llaves

La parte secreta tiene 26 caracteres alfanuméricos. El prefijo público son los primeros 8 caracteres después de ck_live_ / ck_test_: sirve para identificar la llave en soportes y bitácoras sin exponerla.

ck_live_7f3a91c2m4p8q1w7x5n3v9b6t0
└──────┘ └──────┘
 prefijo   último 4: b6t0

Una llave de prueba sólo se puede crear si tu cuenta tiene sandbox_enabled. Las cuentas nuevas lo tienen activo y reciben una llave ck_test_ con scope * al aceptar la invitación.

Scopes

Los scopes limitan lo que una llave puede hacer. Si una llave no tiene el scope requerido, la API responde 403 con SCOPE_FORBIDDEN e incluye required_scope y key_scopes en el cuerpo del problema.

El scope * otorga todos los permisos. Resérvalo para la llave de bootstrap de la cuenta y sustitúyelo por llaves específicas en tus integraciones.

Crear una llave

Se crea desde la consola (panel → Llaves) o por API con una llave que tenga keys:write. El cuerpo acepta name, environment, scopes y expires_in_days (1 a 730).

curl -sS -X POST "https://api.434alchemycode.com/v1/keys" \
  -H "Authorization: Bearer $ALCHEMY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Producción · backend",
    "environment": "live",
    "scopes": ["companies:read", "services:run", "jobs:read", "usage:read"],
    "expires_in_days": 365
  }'

{
  "object": "api_key",
  "id": "1c7e5a92-3d84-4b06-9f17-8a2d6c4e0b53",
  "name": "Producción · backend",
  "prefix": "ck_live_7f3a91c2",
  "last4": "b6t0",
  "environment": "live",
  "scopes": ["companies:read", "services:run", "jobs:read", "usage:read"],
  "created_at": "2026-10-31T16:10:44+00:00",
  "last_used_at": null,
  "expires_at": "2027-10-31T16:10:44+00:00",
  "revoked_at": null,
  "request_count": 0,
  "key": "ck_live_7f3a91c2m4p8q1w7x5n3v9b6t0",
  "warning": "Guarda esta llave: no volverá a mostrarse."
}

Límites de la cuenta: máximo 20 llaves activas. Revocar una llave es inmediato: la siguiente petición con esa llave responde 401 API_KEY_REVOKED.

# Revocar (204 No Content). No borra el historial de consumo.
curl -sS -X DELETE "https://api.434alchemycode.com/v1/keys/1c7e5a92-3d84-4b06-9f17-8a2d6c4e0b53" \
  -H "Authorization: Bearer $ALCHEMY_API_KEY"

Rotación sin downtime

1. Crea una llave nueva con los mismos scopes y un nombre que indique el periodo (Producción · backend 2027-Q1).
2. Despliega el secreto nuevo en tu gestor de secretos y reinicia los procesos que la consumen.
3. Verifica en GET /v1/keys que la llave nueva tenga last_used_at reciente.
4. Revoca la llave anterior y confirma que ya no aparece en el listado.

Errores de autenticación y autorización

Las respuestas 401 incluyen WWW-Authenticate: Bearer realm="alchemy-api". No reintentes un 401 ni un 403: corrige la llave o los scopes; sólo ACCOUNT_SUSPENDED se resuelve con soporte.

Buenas prácticas

• Nunca embebas una llave en frontend, apps móviles ni en repositorios. Usa un backend intermedio.
• Guarda las llaves en un gestor de secretos (Vault, AWS Secrets Manager, Doppler), no en .env de imágenes.
• Una llave por entorno y por integración; nombres que digan quién la usa.
• Aplica el mínimo de scopes: si sólo consultas, no incluyas keys:write.
• Rota cada 90–180 días o de inmediato si hay rotación de personal.
• No pongas la llave en query strings, logs, mensajes de error ni capturas de pantalla.
• Monitorea last_used_at y el consumo por llave; una llave inactiva se revoca.
• Usa ck_test_ en desarrollo y CI; nunca datos reales en sandbox.