Á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:- En la consola, ve a Access → API Keys.
- Crea una nueva key, o abre una key existente para editarla.
- En la lista de ámbitos, busca la fila Fine-grained authorization y habilita ambas casillas (lectura y escritura).
- Haz clic en Save.

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.
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
UtilizaPOST /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:
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
UtilizaGET /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:
reader o writer.
Revocar un rol
UtilizaPOST /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:
204 No Content.
Otorgar acceso público
Otorga un rol a todos los usuarios autenticados estableciendouserId 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 devuelven403 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 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.
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
- Revisa la guía de Autenticación para el uso de API key y JWT.
- Referencia de API para los endpoints de autorización:
POST /api/v1/authorization/llm/grant— Otorgar un rolPOST /api/v1/authorization/llm/revoke— Revocar un rolGET /api/v1/authorization/llm/check— Comprobar permiso