Autenticación y claves de API

La API pública de Kabeen autentica cada petición con una clave de API: una credencial de tipo bearer vinculada al espacio de trabajo. No hay flujo OAuth, ni cookie de sesión, ni paso de inicio de sesión: un administrador del espacio de trabajo crea una clave una sola vez desde la aplicación Kabeen, y usted la presenta en cada petición.

Cómo funciona

• Una clave de API pertenece exactamente a un espacio de trabajo. El espacio de trabajo se liga a la clave en el momento de su creación y nunca se pasa en la ruta, la cadena de consulta ni el cuerpo de la petición: cada endpoint opera implícitamente sobre "el espacio de trabajo al que pertenece esta clave".
• Una clave lleva un conjunto fijo de scopes de permisos (p. ej. applications:read, infrastructure:edit). Cada endpoint requiere exactamente un scope, documentado en la Referencia de endpoints.
• Las claves las crea, rota y revoca un administrador del espacio de trabajo desde la aplicación Kabeen: la propia API pública no expone ningún endpoint para gestionar claves.
• Todo el tráfico de la API pública se autentica como un actor de tipo servicio (la clave), nunca como un miembro humano. Las entradas del registro de auditoría de las llamadas a la API pública registran la clave como actor.

Presentar la clave

Toda clave generada comienza por el prefijo kbn_ (en la práctica kbn_live_...). La API acepta la clave por dos vías equivalentes: use la que mejor se adapte a su cliente HTTP:

Ambas son reconocidas por el mismo mecanismo de autenticación, únicamente en las rutas bajo /public/. Si ambas cabeceras están presentes, X-Api-Key tiene prioridad.

curl https://app.kabeen.io/public/v1/me \
  -H "Authorization: Bearer kbn_live_51gv9c2b7f2a4e6f8c1a0d3b6e9f2c5a8"

curl https://app.kabeen.io/public/v1/me \
  -H "X-Api-Key: kbn_live_51gv9c2b7f2a4e6f8c1a0d3b6e9f2c5a8"

Introspección: GET /me

Antes de configurar cualquier otra cosa, llame a GET /public/v1/me. Solo requiere una clave válida (ningún scope específico) y le indica exactamente a qué espacio de trabajo está vinculado y qué puede hacer la clave — útil tanto como prueba rápida de "¿funciona mi clave?" como para construir integraciones que se adaptan a los scopes que se les han otorgado.

{
  "workspace": {
    "id": "3f9c9f2e-8a71-4e2a-9b0d-2c5f6a1d7e44",
    "name": "Acme Corp"
  },
  "key": {
    "id": "8b2e6a4d-1c3f-4a9e-9d7b-5f0e2c8a6b31",
    "name": "Finance integration",
    "alias": "read"
  },
  "permissions": [
    "applications:read",
    "contracts:read",
    "data:read",
    "infrastructure:read"
  ]
}

• workspace — el espacio de trabajo al que está vinculada esta clave (id + nombre para mostrar).
• key — los metadatos de la propia clave: id, name y alias (el alias a partir del cual se creó — read, write o admin — o null cuando la clave se creó a partir de un conjunto de scopes personalizado y explícito).
• permissions — la lista exacta y ordenada de scopes de permisos que otorga esta clave. Es la fuente de verdad autoritativa de lo que la clave puede llamar; trátela como el contrato, no el nombre del alias.

Scopes de permisos

Cada endpoint requiere exactamente un scope de permiso, con la forma resource:action:

Alias frente a scopes explícitos

Una clave recibe su alcance de exactamente una de dos formas, elegida en el momento de su creación:

• Un alias — read, write o admin — que captura una instantánea del conjunto de permisos del rol de sistema correspondiente en el momento de la creación. El campo alias de la clave (visible en GET /me) registra de qué alias proviene, pero los permissions otorgados son la instantánea congelada, no un vínculo vivo con el rol: si los permisos del rol cambian más adelante, las claves existentes conservan lo que se les otorgó.
• Una lista explícita de códigos resource:action. En este caso alias es null.

En ambos casos, una clave nunca puede recibir un scope que su creador no posea personalmente en el momento de la creación: un administrador no puede emitir una clave con más poder que el de su propia cuenta.

Cuando falta un scope

Llamar a un endpoint sin el scope que requiere devuelve 403 Forbidden:

{
  "code": "insufficient_permission",
  "message": "missing permission: applications:edit",
  "status": 403
}

No codifique de forma rígida suposiciones sobre lo que puede hacer una clave: llame a GET /me y compruebe permissions antes de intentar una llamada, o gestione con elegancia 403/insufficient_permission y hágalo visible a quien administre la clave de la integración.

Ciclo de vida y gestión de las claves

Las claves de API se crean, rotan y revocan por un administrador del espacio de trabajo desde la aplicación Kabeen: la gestión de claves no forma parte de la API pública. Qué esperar a nivel operativo:

• Creación — un administrador da nombre a la clave y define su alcance mediante un alias (read/write/admin) o una lista explícita de códigos de permiso (nunca ambos, nunca ninguno), con una fecha de expiración opcional. El secreto en texto plano se devuelve exactamente una vez, en el momento de la creación — Kabeen no lo almacena de forma recuperable y no puede volver a mostrárselo. Solo se persiste un hash SHA-256 del secreto; lo que puede recuperar después son los metadatos más un breve prefijo de visualización de la clave.
• Rotación — rotar una clave genera un secreto completamente nuevo (mostrado de nuevo una sola vez) e invalida el secreto anterior de inmediato, conservando el mismo id, nombre y scopes de la clave.
• Revocación — una clave revocada o eliminada deja de funcionar de inmediato: cada petición busca la clave por el hash de su secreto y exige que esté actualmente activa, por lo que no hay ventana de caché ni propagación diferida.
• Expiración — una clave creada con fecha de expiración deja de autenticar en cuanto pasa ese instante, aplicado por la misma comprobación por petición y sin caché.

Modos de fallo

Los fallos de autenticación devuelven 401 Unauthorized en todos los casos siguientes:

• No se presenta ninguna credencial (ni Authorization: Bearer ni X-Api-Key).
• La credencial no comienza por el prefijo kbn_ (malformada / no es una clave de Kabeen).
• La clave no corresponde a ninguna clave actualmente activa (incorrecta, revocada o eliminada).
• La clave ha superado su fecha de expiración.

Un 401 real se rechaza en la capa de autenticación, antes de que pueda adjuntarse el cuerpo de error uniforme de la API: la respuesta tiene un cuerpo vacío y una cabecera WWW-Authenticate: Bearer realm="kbine", error="invalid_token". No intente extraer JSON de un 401 — consulte Paginación y errores.

403 Forbidden es un modo de fallo distinto: la clave es válida y está autenticada, pero carece del scope que el endpoint requiere.

Buenas prácticas de seguridad

• Trate la clave como un secreto. Cualquiera que la posea puede actuar como identidad de servicio en su espacio de trabajo, dentro de los permisos que se le hayan otorgado.
• Nunca suba claves al control de versiones ni las incruste en código del lado cliente (JS de navegador, aplicaciones móviles, repositorios públicos). La API pública está diseñada para integraciones servidor a servidor.
• Almacene las claves en variables de entorno o en un gestor de secretos, no en archivos de configuración versionados en un repositorio.
• Prefiera scopes de mínimo privilegio. Una integración de reporting de solo lectura debería recibir una clave read (o una personalizada de solo lectura), no admin.
• Rote periódicamente, e inmediatamente tras cualquier sospecha de exposición: la rotación invalida el secreto anterior en el momento en que se emite el nuevo.
• Revoque las claves que ya no use. La revocación surte efecto en la siguiente petición, así que revocar con prontitud no tiene coste operativo.
• Establezca una expiración para las integraciones temporales o acotadas en el tiempo, en lugar de confiar en una revocación manual posterior.