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:
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.
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.
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
UsePOST /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:
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
UseGET /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 comouser_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:
403 Forbidden.
Um usuário que não pode ler o recurso recebe 404 Not Found.
Listar quem tem acesso
UseGET /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:
Excluir um recurso continua cabendo ao seu proprietário e aos administradores da organização da equipe do recurso.
Revogar uma função
UseDELETE /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:
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, definagrantee_type como team e omita user_id.
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.
reader ou writer recebe este erro ao conceder ou remover uma permissão:
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-Ofestá 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
- Consulte o guia de Autenticação para saber sobre o uso de chaves de API e JWT.
- Consulte Identidade do usuário final para saber como
X-On-Behalf-Ofatribui solicitações aos seus usuários finais. - Referência da API para os endpoints de permissão de conversas:
POST /api/v1/llm/conversations/{conversation_id}/permissions— Conceder uma funçãoGET /api/v1/llm/conversations/{conversation_id}/permissions— Listar permissõesGET /api/v1/llm/conversations/{conversation_id}/permissions/{user_id}— Recuperar a função de um usuárioDELETE /api/v1/llm/conversations/{conversation_id}/permissions/{user_id}— Remover o acesso de um usuário