Saltar al contenido principal
La API de MKA1 proporciona control de acceso basado en roles a nivel de recurso (RBAC) 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:
RolPermisos
ownerOtorgar y revocar roles, además de todo lo que puede hacer writer
writerModificar el recurso, además de todo lo que puede hacer reader
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 apropiada. También puedes otorgar acceso público usando "*" como ID de usuario, pero solo para los roles 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. 
import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

// Otorgar acceso de lector a user_bob en un recurso de conversación
await mka1.permissions.llm.grant({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  userId: 'user_bob',
  role: 'reader',
})
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. 
import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

// Comprobar si el llamador tiene acceso de lector
const result = await mka1.permissions.llm.check({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  role: 'reader',
})

console.log(result.allowed) // true

{ "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. 
import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

// Revocar acceso de lector a user_bob
await mka1.permissions.llm.revoke({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  userId: 'user_bob',
  role: 'reader',
})
Una revocación exitosa devuelve 204 No Content.

​
Otorgar acceso público

Otorga un rol a todos los usuarios autenticados estableciendo userId como "*". El acceso público está restringido a los roles writer y reader — no puedes hacer que alguien sea propietario público. 
await mka1.permissions.llm.grant({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  userId: '*',
  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

Este recorrido demuestra 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. 
import { SDK } from '@meetkai/mka1'

const mka1 = new SDK({ bearerAuth: 'Bearer YOUR_API_KEY' })

// Paso 1 — Alice crea una conversación (ella se convierte en la propietaria)
const conv = await mka1.llm.conversations.create(
  { metadata: { project: 'acme' } },
  { headers: { 'X-On-Behalf-Of': 'user_alice' } }
)
const resourceId = conv.id

// Paso 2 — Alice otorga acceso de lector a Bob
await mka1.permissions.llm.grant(
  {
    resourceType: 'conversation',
    resourceId,
    userId: 'user_bob',
    role: 'reader',
  },
  { headers: { 'X-On-Behalf-Of': 'user_alice' } }
)

// Paso 3 — Comprobar los permisos de Bob
// Bob tiene acceso de lector → permitido
const bobReader = await mka1.permissions.llm.check(
  {
    resourceType: 'conversation',
    resourceId,
    role: 'reader',
  },
  { headers: { 'X-On-Behalf-Of': 'user_bob' } }
)
console.log('Bob reader:', bobReader.allowed) // true

// Bob NO tiene acceso de escritor → denegado
const bobWriter = await mka1.permissions.llm.check(
  {
    resourceType: 'conversation',
    resourceId,
    role: 'writer',
  },
  { headers: { 'X-On-Behalf-Of': 'user_bob' } }
)
console.log('Bob writer:', bobWriter.allowed) // false

// Paso 4 — Bob intenta otorgar (falla con 403)
try {
  await mka1.permissions.llm.grant(
    {
      resourceType: 'conversation',
      resourceId,
      userId: 'user_charlie',
      role: 'reader',
    },
    { headers: { 'X-On-Behalf-Of': 'user_bob' } }
  )
} catch (err) {
  console.log('Bob grant rejected:', err.statusCode) // 403
}

// Paso 5 — Alice revoca el acceso de Bob
await mka1.permissions.llm.revoke(
  {
    resourceType: 'conversation',
    resourceId,
    userId: 'user_bob',
    role: 'reader',
  },
  { headers: { 'X-On-Behalf-Of': 'user_alice' } }
)

// Paso 6 — Verificar que Bob ahora está denegado
const bobAfterRevoke = await mka1.permissions.llm.check(
  {
    resourceType: 'conversation',
    resourceId,
    role: 'reader',
  },
  { headers: { 'X-On-Behalf-Of': 'user_bob' } }
)
console.log('Bob after revoke:', bobAfterRevoke.allowed) // false

​
Próximos pasos