02 — Autenticación

Formato

Toda solicitud a la API pública lleva la clave en la cabecera Authorization, como un bearer token:

Authorization: Bearer yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e

No hay un esquema alternativo (sin cabecera personalizada, sin parámetro de consulta) — pasar la clave por la URL queda deliberadamente fuera de soporte porque las URLs terminan en logs de servidores intermedios.

Hoy toda clave empieza con yk_live_ y opera sobre los cobros reales del comercio: todavía no existen claves de prueba yk_test_ ni un comercio de pruebas. Llegarán con el modo de pruebas; GET /v1/me ya informa el modo de la clave (mode, hoy siempre live) para que tu integración no tenga que cambiar cuando existan.

Alcances (scopes)

Cada clave se crea con una lista explícita de alcances. Una solicitud a un recurso que la clave no cubre responde 403 FORBIDDEN, no 401 — la clave es válida, simplemente no alcanza para esa operación.

Sigue el principio de menor privilegio: si tu integración solo lee transacciones, crea la clave únicamente con transactions:read. Si necesitas distintos niveles de acceso para distintos sistemas, crea una clave por sistema en vez de compartir una con alcance amplio.

Ciclo de vida de una clave

• Creación: POST /v1/api-keys (requiere sesión de panel con rol ADMIN, no se puede crear una clave con otra clave).
• Listado: GET /v1/api-keys devuelve key_prefix, nunca el valor completo.
• Revocación: DELETE /v1/api-keys/{id} — inmediata, no reversible. Las solicitudes en curso con esa clave pueden completarse, las siguientes reciben 401 UNAUTHENTICATED.
• Expiración opcional: al crearla puedes fijar expires_at; pasada esa fecha la clave deja de aceptarse automáticamente.

No existe endpoint para "rotar" una clave de API conservando el mismo id (a diferencia del secreto de webhook, que sí rota in-place — ver guía 04): para rotar, crea la nueva, migra tu integración, y luego revoca la anterior.

Claves por plan

Cada plan tiene su propio cupo de claves activas, independiente del de webhooks: conectar un sistema no le quita un webhook al comercio, ni al revés.

Cuentan las claves sin revocar, aunque estén vencidas. Superar el cupo responde 422 PLAN_LIMIT_EXCEEDED con details.limit y details.current.

Verificar la clave: GET /v1/me

Antes de operar, consulta con qué comercio, alcances, plan y límite funciona la clave. Así un alcance que falta se descubre al conectar la integración, no con el primer 403 en producción.

curl https://api.yallego.app/v1/me \
  -H "Authorization: Bearer yk_live_9f8c2a1e4b7d3f6a8c2e1b5d7f9a3c6e"

{
  "mode": "live",
  "tenant": { "id": "5d1e2f3a-…", "name": "Bodega Rosa" },
  "plan": { "code": "COMERCIO", "name": "Comercio", "realtime": true },
  "rate_limit": { "limit": 300, "window_seconds": 60 },
  "api_key": {
    "id": "9f8c2a1e-…",
    "label": "Integración POS",
    "key_prefix": "yk_live_9f8c2a1e",
    "scopes": ["transactions:read", "webhooks:write"],
    "created_at": "2026-05-14T18:45:00Z",
    "expires_at": null,
    "last_used_at": "2026-05-15T09:12:40Z"
  }
}

• No consume tu límite de solicitudes. Las cabeceras X-RateLimit-* de la respuesta informan cuánto llevas en el minuto, sin sumar esta consulta.
• Un cambio de plan, alcances o vencimiento se refleja en menos de un minuto, igual que en el resto de la API.
• Solo acepta claves de API: con la sesión del panel responde 403 FORBIDDEN (el panel usa GET /v1/auth/me). Una clave inválida, revocada o vencida responde 401 UNAUTHENTICATED.

Errores de autenticación

El tiempo real no responde con HTTP: si el plan no incluye el WebSocket o la clave no tiene realtime:subscribe, el canal envía el evento error con FORBIDDEN y cierra la conexión (ver 06 — Catálogo de eventos).

// 401 Unauthorized
{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "La clave de API no es válida.",
    "request_id": "b7f3a2e1-..."
  }
}

Buenas prácticas

• Trata cada clave como una contraseña: nunca la incluyas en código fuente versionado, en un cliente móvil o en JavaScript que corre en el navegador del usuario final.
• Usa una clave distinta por sistema y por entorno para poder revocar una sin afectar las demás. Mientras no existan las claves yk_test_, la clave de tu entorno de pruebas también opera sobre los cobros reales del comercio: dale solo los alcances de lectura que necesites.
• Monitorea X-RateLimit-Remaining (ver 09 — Límites de tasa) para detectar un uso anómalo antes de que te bloquee 429.