Saltar al contenido principal
La API de MKA1 proporciona control de acceso basado en roles (RBAC) a nivel de recurso a través de los endpoints de autorización. Utiliza estos endpoints para otorgar, comprobar y revocar permisos sobre recursos LLM para usuarios específicos.
Cada endpoint de esta guía está protegido por ámbitos de API key dedicados: write:fine-grained-authorization (otorgar, revocar) y read:fine-grained-authorization (comprobar). Las solicitudes realizadas con una key que carece de ellos fallan con 403 Forbidden independientemente de la propiedad del recurso. Estos son ámbitos de administrador: solo los administradores de la organización pueden añadirlos a una API key, por lo que, si no eres administrador, necesitarás una key emitida por uno para completar esta guía. Consulta Ámbitos requeridos de la API key para saber cómo habilitarlos.

Ámbitos requeridos de la API key

Las API keys llevan un conjunto fijo de ámbitos, y los ámbitos de autorización granular no forman parte de cada key de forma predeterminada: Ambos son ámbitos de administrador — solo los administradores de la organización pueden habilitarlos en una API key. Si no eres administrador, las casillas no están disponibles para ti: pide a un administrador que te emita una key con estos ámbitos, o que los añada a tu key existente. Si a tu key le falta un ámbito, la API rechaza la solicitud antes de que se realice cualquier comprobación de propiedad:

Habilitar los ámbitos en la consola de la plataforma

Como administrador de la organización, puedes crear una key con estos ámbitos, o añadirlos a una key existente, en platform.mka1.com/admin/api-keys:
  1. En la consola, ve a Access → API Keys.
  2. Crea una nueva key, o abre una key existente para editarla.
  3. En la lista de ámbitos, busca la fila Fine-grained authorization y habilita ambas casillas (lectura y escritura).
  4. Haz clic en Save.
El editor de ámbitos de API key con ambas casillas de Fine-grained authorization habilitadas y resaltadas Para más información sobre la creación de API keys y cómo funcionan los ámbitos en general, consulta la guía de introducción a la plataforma.

Cómo funciona la autorización de recursos

Cada recurso LLM (completado, archivo, almacén vectorial, conversación, respuesta o habilidad) puede tener roles asignados por usuario. Tres roles forman una jerarquía estricta: Los IDs de recursos se crean cuando realizas llamadas a la API de LLM. Por ejemplo, crear una conversación devuelve un ID conv_, crear una respuesta devuelve un ID resp_, y subir un archivo devuelve un ID file_. El llamador autenticado (o el usuario final especificado mediante X-On-Behalf-Of) se convierte automáticamente en el propietario de ese recurso. Utiliza el ID de recurso devuelto con los endpoints de autorización a continuación para gestionar el acceso de otros usuarios. Solo los propietarios pueden otorgar o revocar roles. Si un no propietario intenta otorgar o revocar, la API devuelve 403 Forbidden. Estas autorizaciones son aplicadas por el backend de MKA1 en cada solicitud. Cualquier intento de leer, modificar o eliminar un recurso al que el llamador no tenga acceso será rechazado con una respuesta de error adecuada. También puedes otorgar acceso público usando "*" como el ID de usuario, pero solo para los roles de writer o reader.

Configuración: crear un recurso como Alice

Los ejemplos de esta guía se basan unos en otros y utilizan dos usuarios finales:
  • Alice (user_alice) crea una conversación, lo que la convierte en su propietaria.
  • A Bob (user_bob) se le otorga acceso, lo ejerce y luego se le revoca.
El encabezado X-On-Behalf-Of controla como qué usuario final actúa una llamada. Empieza creando una conversación como Alice y capturando su ID — cada fragmento a continuación lo utiliza:
Otorgar, comprobar y revocar solo funcionan contra un ID de recurso real que el usuario actuante posee. Dos errores comunes producen un error 403 Forbidden “is not an owner”: pasar un ID inventado (como conv-abc-123), u omitir X-On-Behalf-Of — sin él, la llamada actúa como el usuario de servicio propio de la API key, no como Alice.

Otorgar un rol a un usuario

Utiliza POST /api/v1/authorization/llm/grant para asignar un rol a un usuario sobre un recurso. El llamador debe ser el propietario del recurso, por lo que Alice es quien otorga:
Un otorgamiento exitoso devuelve 204 No Content. El resourceType debe ser uno de: completion, file, vector_store, conversation, response o skill. El role debe ser uno de: owner, writer o reader.

Comprobar el permiso de un usuario

Utiliza GET /api/v1/authorization/llm/check para verificar si el llamador autenticado tiene un rol específico sobre un recurso. La respuesta contiene un booleano allowed. Aquí Bob — a quien se le acaba de otorgar reader — comprueba su propio acceso:
Debido a que los roles son jerárquicos, un propietario también pasa una comprobación de reader o writer.

Revocar un rol

Utiliza POST /api/v1/authorization/llm/revoke para eliminar un rol de un usuario. Solo el propietario del recurso puede revocar, por lo que Alice elimina el acceso de Bob:
Una revocación exitosa devuelve 204 No Content.

Otorgar acceso público

Otorga un rol a todos los usuarios autenticados estableciendo userId en "*". El acceso público está restringido a los roles de writer y reader — no puedes hacer que alguien sea propietario público. Como en cualquier otorgamiento, el llamador debe ser el propietario del recurso (Alice):

Manejar errores de autorización

Los endpoints de autorización devuelven 403 Forbidden por dos razones distintas — comprueba el message para diferenciarlas. A la API key le falta un ámbito requerido. La solicitud se rechaza antes de cualquier comprobación de propiedad. Soluciónalo habilitando los ámbitos de autorización granular en tu key — consulta Ámbitos requeridos de la API key.
El llamador no es el propietario del recurso. Solo los propietarios pueden otorgar o revocar:
Además de un problema genuino de permisos, este error tiene dos causas comunes:
  • El ID de recurso no existe — debes crear el recurso primero y usar su ID real; los IDs de marcador de posición se rechazan como no poseídos.
  • Falta X-On-Behalf-Of — la llamada actúa entonces como el usuario de servicio propio de la API key (el ID de usuario opaco en el mensaje anterior), no como el usuario final que posee el recurso.
Comprueba siempre el rol del llamador antes de intentar cambios de permisos, o maneja la respuesta 403 en tu aplicación.

Ejemplo de extremo a extremo: dos usuarios con diferentes roles

Esta guía muestra perfiles de usuario distintos con permisos diferenciados. Alice crea una conversación (convirtiéndose en su propietaria), luego otorga acceso de lectura a Bob. Verificamos que Bob puede leer pero no puede escribir, y que Bob no puede otorgar permisos a otros.

Próximos pasos