Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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:
RolPuede hacer
ownerOtorgar y revocar roles, además de todo lo que puede hacer un escritor
writerModificar el recurso, además de todo lo que puede hacer un lector
readerLeer el recurso
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.

​
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. 
mka1 permissions llm grant \
  --resource-type conversation \
  --resource-id conv-abc-123 \
  --user-id user_bob \
  --role reader \
  -H 'X-On-Behalf-Of: user_alice'
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. 
mka1 permissions llm check \
  --resource-type conversation \
  --resource-id conv-abc-123 \
  --role reader \
  -H 'X-On-Behalf-Of: user_bob'

{ "allowed": true }
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. 
mka1 permissions llm revoke \
  --resource-type conversation \
  --resource-id conv-abc-123 \
  --user-id user_bob \
  --role reader \
  -H 'X-On-Behalf-Of: user_alice'
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. 
mka1 permissions llm grant \
  --resource-type conversation \
  --resource-id conv-abc-123 \
  --user-id '*' \
  --role reader

​
Manejar errores de autorización

Cuando un no propietario intenta otorgar o revocar, la API devuelve 403 Forbidden: 
{
  "error": "Forbidden",
  "message": "Only resource owners can grant or revoke permissions"
}
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. 
# Paso 1 — Alice crea una conversación (ella se convierte en la propietaria)
CONV_JSON=$(mka1 llm conversations create \
  --body '{ "metadata": { "project": "acme" } }' \
  -H 'X-On-Behalf-Of: user_alice' \
  -o json)
RESOURCE_ID=$(echo "$CONV_JSON" | jq -r '.id')

# Paso 2 — Alice otorga acceso de lectura a Bob
mka1 permissions llm grant \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --user-id user_bob \
  --role reader \
  -H 'X-On-Behalf-Of: user_alice'

# Paso 3 — Comprobar que Bob tiene acceso de lectura (allowed: true)
mka1 permissions llm check \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --role reader \
  -H 'X-On-Behalf-Of: user_bob'

# Paso 3b — Comprobar que Bob NO tiene acceso de escritura (allowed: false)
mka1 permissions llm check \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --role writer \
  -H 'X-On-Behalf-Of: user_bob'

# Paso 4 — Bob intenta otorgar (devuelve 403 Forbidden)
mka1 permissions llm grant \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --user-id user_charlie \
  --role reader \
  -H 'X-On-Behalf-Of: user_bob'

# Paso 5 — Alice revoca el acceso de Bob
mka1 permissions llm revoke \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --user-id user_bob \
  --role reader \
  -H 'X-On-Behalf-Of: user_alice'

# Paso 6 — Verificar que Bob ahora está denegado (allowed: false)
mka1 permissions llm check \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --role reader \
  -H 'X-On-Behalf-Of: user_bob'

​
Próximos pasos