Escopos de chave de API obrigatórios
As chaves de API têm um conjunto fixo de escopos, e os escopos de autorização refinada não fazem parte de todas as chaves por padrão:
Ambos são escopos de administrador — somente administradores da organização podem habilitá-los em uma chave de API.
Se você não for administrador, as opções não estarão disponíveis para você: peça a um administrador para emitir uma chave com esses escopos ou adicioná-los à sua chave existente.
Se sua chave não tiver um escopo, a API rejeitará a solicitação antes de realizar qualquer verificação de propriedade:
Habilite os escopos no console da plataforma
Como administrador da organização, você pode criar uma chave com esses escopos ou adicioná-los a uma chave existente em platform.mka1.com/admin/api-keys:- No console, acesse Acesso → Chaves de API.
- Crie uma nova chave ou abra uma chave existente para editá-la.
- Na lista de escopos, localize a linha Autorização refinada e habilite ambas as caixas de seleção (leitura e gravação).
- Clique em Salvar.

Como funciona a autorização de recursos
Cada recurso de LLM (conclusão, arquivo, repositório de vetores, conversa, resposta ou habilidade) pode ter funções por usuário atribuídas a ele. Três funções formam uma hierarquia rígida:
Os IDs de recursos são criados quando você faz chamadas à API de LLM.
Por exemplo, criar uma conversa retorna um ID
conv_, criar uma resposta retorna um ID resp_, e enviar um arquivo retorna um ID file_.
O chamador autenticado (ou o usuário final especificado por X-On-Behalf-Of) torna-se automaticamente o proprietário desse recurso.
Use o ID de recurso retornado com os endpoints de autorização abaixo para gerenciar o acesso de outros usuários.
Somente proprietários podem conceder ou revogar funções.
Se um não proprietário tentar conceder ou revogar, a API retornará 403 Forbidden.
Essas autorizações são aplicadas pelo backend MKA1 em todas as solicitações.
Qualquer tentativa de ler, modificar ou excluir um recurso ao qual o chamador não tenha acesso é rejeitada com uma resposta de erro apropriada.
Você também pode conceder acesso público usando ”*” como ID de usuário, mas somente para as funções writer ou reader.
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 revogado.
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:
Conceder, verificar e revogar só funcionam com um ID de recurso real que o usuário atuante possui.
Dois erros comuns produzem um erro
403 Forbidden “is not an owner”: fornecer um ID inventado (como conv-abc-123) ou omitir X-On-Behalf-Of — sem ele, a chamada atua como o próprio usuário de serviço da chave de API, e não como Alice.Conceder uma função a um usuário
UsePOST /api/v1/authorization/llm/grant para atribuir uma função a um usuário em um recurso.
O chamador deve ser o proprietário do recurso, portanto Alice faz a concessão:
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
UseGET /api/v1/authorization/llm/check para verificar se o chamador autenticado tem uma função específica em um recurso.
A resposta contém um booleano allowed.
Aqui, Bob — que acabou de receber reader — verifica seu próprio acesso:
reader ou writer.
Revogar uma função
UsePOST /api/v1/authorization/llm/revoke para remover uma função de um usuário.
Somente o proprietário do recurso pode revogar, então Alice remove o acesso de Bob:
204 No Content.
Conceder acesso público
Conceda uma função a todos os usuários autenticados definindouserId como ”*”.
O acesso público é restrito às funções writer e reader — você não pode tornar alguém um proprietário público.
Como em qualquer concessão, o chamador deve ser o proprietário do recurso (Alice):
Lidar com erros de autorização
Os endpoints de autorização retornam403 Forbidden por dois motivos distintos — verifique a message para diferenciá-los.
A chave de API não tem um escopo obrigatório. A solicitação é rejeitada antes de qualquer verificação de propriedade.
Corrija isso habilitando os escopos de autorização refinada na sua chave — consulte Escopos de chave de API obrigatórios.
- O ID do recurso não existe — você deve criar o recurso primeiro e usar seu ID real; IDs de placeholder são rejeitados como não pertencentes.
X-On-Behalf-Ofestá ausente — a chamada então atua como o próprio usuário de serviço da chave de API (o ID de usuário opaco na mensagem acima), e não como o usuário final que possui 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, mas não pode gravar, e que Bob não pode conceder permissões a outros.Próximas etapas
- Consulte o guia de Autenticação para saber sobre o uso de chaves de API e JWT.
- Referência da API para os endpoints de autorização:
POST /api/v1/authorization/llm/grant— Conceder uma funçãoPOST /api/v1/authorization/llm/revoke— Revogar uma funçãoGET /api/v1/authorization/llm/check— Verificar permissão