Pular para o conteúdo 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.

A API MKA1 fornece controle de acesso baseado em papéis (RBAC) em nível de 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 LLM (completação, arquivo, vetor store, conversa, resposta ou habilidade) pode ter papéis atribuídos por usuário. Três papéis formam uma hierarquia estrita:
PapelPode fazer
proprietárioConceder e revogar papéis, além de tudo que o escritor pode fazer
escritorModificar o recurso, além de tudo que o leitor pode fazer
leitorLer o recurso
IDs de recursos são criados quando você faz chamadas à API LLM. Por exemplo, criar uma conversa retorna um ID conv_, criar uma resposta retorna um ID resp_, e fazer upload de um arquivo retorna um ID file_. O chamador autenticado (ou o usuário final especificado via X-On-Behalf-Of) torna-se automaticamente o proprietário desse recurso. Use o ID do recurso retornado com os endpoints de autorização abaixo para gerenciar o acesso de outros usuários. Somente proprietários podem conceder ou revogar papéis. Se um não-proprietário tentar conceder ou revogar, a API retorna 403 Forbidden. Essas autorizações são aplicadas pelo backend do MKA1 em cada requisição. Qualquer tentativa de ler, modificar ou excluir um recurso ao qual o chamador não tem acesso é rejeitada com uma resposta de erro apropriada. Você também pode conceder acesso público usando "*" como o ID do usuário, mas apenas para os papéis escritor ou leitor.

​
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 chamador deve ser o proprietário do 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'
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 chamador autenticado possui um papel específico em um recurso. A resposta contém um 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 }
Como os papéis são hierárquicos, um proprietário 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 proprietário do recurso pode revogar. 
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'
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 proprietário público. 
mka1 permissions llm grant \
  --resource-type conversation \
  --resource-id conv-abc-123 \
  --user-id '*' \
  --role reader

​
Lidar com erros de autorização

Quando um não-proprietário 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 chamador antes de tentar alterar permissões, ou trate a resposta 403 em sua aplicação.

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

Este passo a passo demonstra perfis de usuários distintos com permissões diferenciadas. Alice cria uma conversa (tornando-se proprietária), 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. 
# Passo 1 — Alice cria uma conversa (ela se torna a proprietária)
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')

# Passo 2 — Alice concede acesso de leitura 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'

# Passo 3 — Verifique que Bob tem acesso de leitura (allowed: true)
mka1 permissions llm check \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --role reader \
  -H 'X-On-Behalf-Of: user_bob'

# Passo 3b — Verifique que Bob NÃO tem acesso de escrita (allowed: false)
mka1 permissions llm check \
  --resource-type conversation \
  --resource-id "$RESOURCE_ID" \
  --role writer \
  -H 'X-On-Behalf-Of: user_bob'

# Passo 4 — Bob tenta conceder (retorna 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'

# Passo 5 — Alice revoga o acesso 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'

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

​
Próximos passos