Saltar para o conteúdo principal
A MKA1 API oferece controle de acesso baseado em papéis (RBAC) no nível do recurso por meio dos endpoints de autorização. Use esses endpoints para conceder, verificar e revogar permissões em recursos LLM para usuários específicos.

​
Como funciona a autorização de recursos

Cada recurso de LLM (completion, file, vector_store, conversation, response ou skill) pode ter papéis atribuídos por usuário. Três papéis formam uma hierarquia estrita:
PapelPode fazer
ownerConceder e revogar papéis, além de tudo que o writer pode fazer
writerModificar o recurso, além de tudo que o reader pode fazer
readerLer o recurso
Os IDs de recurso são criados quando você faz chamadas à API de LLM. Por exemplo, criar uma conversation retorna um ID conv_, criar uma response retorna um ID resp_ e fazer upload de um file retorna um ID file_. O solicitante autenticado, ou o end user especificado em X-On-Behalf-Of, se torna automaticamente o owner desse recurso. Use o ID de recurso retornado com os endpoints de autorização abaixo para gerenciar o acesso de outros usuários. Somente quem tem o papel owner pode conceder ou revogar papéis. Se alguém que não é owner tentar conceder ou revogar, a API retorna 403 Forbidden. Essas autorizações são aplicadas pelo backend da MKA1 em todas as requisições. Qualquer tentativa de ler, modificar ou excluir um recurso ao qual o solicitante não tem acesso é rejeitada com uma resposta de erro apropriada. Você também pode conceder acesso público usando "*" como ID de usuário, mas apenas para os papéis writer ou reader.

​
Conceder um papel a um usuário

Use POST /api/v1/authorization/llm/grant para atribuir um papel a um usuário em um recurso. O solicitante deve ser o owner do recurso. 
import { SDK } from '@meetkai/mka1'

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

// Conceder o papel `reader` a user_bob em uma `conversation`
await mka1.permissions.llm.grant({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  userId: 'user_bob',
  role: 'reader',
})
Uma concessão bem-sucedida retorna 204 No Content. O resourceType deve ser um dos seguintes: completion, file, vector_store, conversation, response ou skill. O role deve ser um dos seguintes: owner, writer ou reader.

​
Verificar a permissão de um usuário

Use GET /api/v1/authorization/llm/check para verificar se o solicitante autenticado tem um papel específico em um recurso. A resposta contém um booleano allowed. 
import { SDK } from '@meetkai/mka1'

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

// Verificar se o solicitante tem o papel `reader`
const result = await mka1.permissions.llm.check({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  role: 'reader',
})

console.log(result.allowed) // true

{ "allowed": true }
Como os papéis são hierárquicos, um owner também passa em uma verificação de reader ou writer.

​
Revogar um papel

Use POST /api/v1/authorization/llm/revoke para remover um papel de um usuário. Apenas o owner do recurso pode revogar. 
import { SDK } from '@meetkai/mka1'

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

// Revogar o papel `reader` de user_bob
await mka1.permissions.llm.revoke({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  userId: 'user_bob',
  role: 'reader',
})
Uma revogação bem-sucedida retorna 204 No Content.

​
Conceder acesso público

Conceda um papel a todos os usuários autenticados definindo userId como "*". O acesso público é restrito aos papéis writer e reader. Você não pode tornar alguém um owner público. 
await mka1.permissions.llm.grant({
  resourceType: 'conversation',
  resourceId: 'conv-abc-123',
  userId: '*',
  role: 'reader',
})

​
Lidar com erros de autorização

Quando alguém que não é owner tenta conceder ou revogar, a API retorna 403 Forbidden: 
{
  "error": "Forbidden",
  "message": "Only resource owners can grant or revoke permissions"
}
Sempre verifique o papel do solicitante antes de tentar alterar permissões, ou trate a resposta 403 na sua aplicação.

​
Exemplo de ponta a ponta: dois usuários com papéis diferentes

Este passo a passo demonstra perfis de usuário distintos com permissões diferentes. Alice cria uma conversation, torna-se owner e depois concede acesso de leitura a Bob. Verificamos que Bob pode ler mas não pode escrever, e que Bob não pode conceder permissões a outros. 
import { SDK } from '@meetkai/mka1'

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

// Etapa 1 — Alice cria uma `conversation` e se torna `owner`
const conv = await mka1.llm.conversations.create(
  { metadata: { project: 'acme' } },
  { headers: { 'X-On-Behalf-Of': 'user_alice' } }
)
const resourceId = conv.id

// Etapa 2 — Alice concede o papel `reader` a Bob
await mka1.permissions.llm.grant(
  {
    resourceType: 'conversation',
    resourceId,
    userId: 'user_bob',
    role: 'reader',
  },
  { headers: { 'X-On-Behalf-Of': 'user_alice' } }
)

// Etapa 3 — Verificar as permissões de Bob
// Bob tem o papel `reader` -> 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 NÃO tem o papel `writer` -> negado
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

// Etapa 4 — Bob tenta conceder (falha com 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 rejeitado:', err.statusCode) // 403
}

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

// Etapa 6 — Verificar que Bob agora é negado
const bobAfterRevoke = await mka1.permissions.llm.check(
  {
    resourceType: 'conversation',
    resourceId,
    role: 'reader',
  },
  { headers: { 'X-On-Behalf-Of': 'user_bob' } }
)
console.log('Bob após revogação:', bobAfterRevoke.allowed) // false

​
Próximos passos