Pular para o conteúdo principal
Todo recurso que você cria por meio da API MKA1 pertence ao usuário que o criou. Use os endpoints de permissão de um recurso para compartilhá-lo com outros usuários, ver quem tem acesso e remover esse acesso. Cada recurso compartilhável tem os mesmos quatro endpoints em seu próprio caminho: Este guia percorre os quatro em uma conversa. Respostas, arquivos, habilidades e vector stores funcionam da mesma forma.

Escopos de chave de API obrigatórios

Os endpoints de permissão usam os escopos do recurso ao qual pertencem. Listar e recuperar permissões exige o escopo de leitura do recurso. Conceder e remover permissões exige o escopo de gravação do recurso. Uma chave que já pode criar e ler um recurso pode compartilhá-lo. Nenhum escopo de autorização separado é necessário. Se sua chave não tiver um escopo, a API rejeitará a solicitação antes de examinar o recurso:
Para alterar os escopos de uma chave, consulte o guia de introdução à plataforma.

Como funciona a autorização de recursos

Um usuário tem uma de três funções em um recurso: O chamador autenticado, ou o usuário final indicado em X-On-Behalf-Of, torna-se o proprietário de cada recurso que cria. Um recurso tem um único proprietário, definido quando ele é criado. Você pode conceder reader e writer; não pode conceder, alterar nem remover owner. Somente dois tipos de chamador podem gerenciar as permissões de um recurso:
  • O proprietário do recurso.
  • Um administrador da organização da equipe do recurso, chamando sem X-On-Behalf-Of.
Um usuário que recebeu reader ou writer pode usar o recurso e recuperar a própria função, mas não pode ver nem alterar com quem mais ele está compartilhado. A API aplica essas funções em todas as solicitações. Um recurso compartilhado é acessível pelo seu ID. Ele não aparece nos resultados de listagem do outro usuário, que contêm apenas os recursos dos quais esse usuário é proprietário. Uma permissão abrange um único recurso. Compartilhar uma conversa não compartilha as respostas contidas nela, e compartilhar uma resposta não compartilha sua conversa.

Configuração: crie um recurso como Alice

Os exemplos deste guia se baseiam uns nos outros e usam dois usuários finais:
  • Alice (user_alice) cria uma conversa, o que faz dela a proprietária.
  • Bob (user_bob) recebe acesso, o utiliza e tem seu acesso removido.
O cabeçalho X-On-Behalf-Of controla como qual usuário final uma chamada atua. Comece criando uma conversa como Alice e capturando seu ID — todos os snippets abaixo o utilizam:
Os endpoints de permissão só funcionam com um ID de recurso real que o usuário atuante consegue acessar. Um ID inventado (como conv-abc-123) retorna 404 Not Found. O mesmo acontece ao omitir X-On-Behalf-Of quando sua chave de API não pertence a um administrador da organização — a chamada então atua como o próprio usuário da chave, que não pode ler a conversa de Alice.

Conceder uma função a um usuário

Use POST /api/v1/llm/conversations/{conversation_id}/permissions para atribuir a um usuário uma função em uma conversa. O chamador deve poder gerenciar as permissões da conversa, portanto Alice faz a concessão:
A resposta é a permissão que passa a valer:
O role deve ser reader ou writer. writer inclui reader. Uma concessão substitui qualquer função que o usuário já tinha; portanto, conceder writer a um leitor o promove e conceder reader a um editor o rebaixa. O user_id é o ID de um membro da sua organização ou o ID de usuário final que você envia em X-On-Behalf-Of. Ele não é verificado em um diretório; portanto, um ID digitado incorretamente é aceito e permanece na lista até que você o remova.

Verificar a permissão de um usuário

Use GET /api/v1/llm/conversations/{conversation_id}/permissions/{user_id} para recuperar a função que um usuário tem e de onde ela vem. Aqui, Alice verifica o que Bob pode fazer com a conversa dela:
role é a função mais alta que o usuário tem, ou null quando ele não tem nenhuma. source indica de onde vem a função: Um usuário com none ainda pode acessar o recurso se for administrador da organização da equipe do recurso.

Verificar a sua própria função

Qualquer usuário que possa ler um recurso pode recuperar a própria função nele, passando o próprio ID como user_id. Use isso para saber se o usuário atual pode escrever em um recurso que foi compartilhado com ele. Aqui, Bob verifica o que pode fazer com a conversa de Alice:
A resposta tem o mesmo formato da anterior. Um usuário que não pode gerenciar as permissões do recurso só pode recuperar a própria função: perguntar sobre qualquer outro usuário retorna 403 Forbidden. Um usuário que não pode ler o recurso recebe 404 Not Found.

Listar quem tem acesso

Use GET /api/v1/llm/conversations/{conversation_id}/permissions para listar todos que têm uma função em uma conversa. A lista é completa e não é paginada. O proprietário vem primeiro, depois a concessão à equipe, quando houver, e então os usuários individuais:

Usar um recurso compartilhado

Um usuário que tem uma função usa o recurso por meio dos endpoints normais do recurso, pelo ID. Bob agora pode ler a conversa de Alice:
O que cada função permite depende do recurso: Excluir um recurso continua cabendo ao seu proprietário e aos administradores da organização da equipe do recurso.

Revogar uma função

Use DELETE /api/v1/llm/conversations/{conversation_id}/permissions/{user_id} para remover todas as funções que um usuário tem em uma conversa. Alice remove o acesso de Bob:
Remover o acesso de um usuário que não tem nenhuma função retorna 404 Not Found. A permissão do proprietário não pode ser removida; em vez disso, exclua o recurso.

Compartilhar com toda a sua equipe

Para dar uma função a todos os membros da equipe do recurso, defina grantee_type como team e omita user_id.
Na lista, a concessão à equipe tem grantee_type definido como team e user_id definido como null. Para recuperá-la ou removê-la, use team no lugar do ID de usuário: /permissions/team. Um recurso nunca é compartilhado fora de sua equipe. Usuários de outras equipes e de outras organizações não podem acessá-lo, quaisquer que sejam as permissões que ele tenha.

Lidar com erros de autorização

Os endpoints de permissão respondem com um destes erros quando uma solicitação é recusada: Um 403 Forbidden tem duas causas distintas — verifique a message para diferenciá-las. A chave de API não tem um escopo obrigatório. A solicitação é rejeitada antes de o recurso ser consultado. Corrija isso adicionando os escopos do recurso à sua chave — consulte Escopos de chave de API obrigatórios.
O chamador não pode gerenciar as permissões do recurso. Um usuário que recebeu reader ou writer recebe este erro ao conceder ou remover uma permissão:
O mesmo usuário recebe este erro ao listar as permissões ou recuperar a função de outro usuário:
Um 404 Not Found em um recurso que você sabe que existe tem duas causas comuns:
  • O ID do recurso está errado — você deve criar o recurso primeiro e usar seu ID real.
  • X-On-Behalf-Of está ausente ou indica o usuário final errado — a chamada então atua como um usuário que não pode ler o recurso.

Exemplo completo: dois usuários com funções diferentes

Este passo a passo demonstra perfis de usuários distintos com permissões diferenciadas. Alice cria uma conversa (tornando-se sua proprietária) e depois concede acesso de leitura a Bob. Verificamos que Bob pode ler a conversa, mas não pode compartilhá-la com outros, e que ele perde o acesso quando Alice o remove.

Próximas etapas