Skip to main content
A API MKA1 fornece controle de acesso baseado em funções (RBAC) no nível de recurso por meio dos endpoints de autorização. Use esses endpoints para conceder, verificar e revogar permissões em recursos de LLM para usuários específicos.
Todos os endpoints deste guia são controlados por escopos de chave de API dedicados: write:fine-grained-authorization (conceder, revogar) e read:fine-grained-authorization (verificar). Solicitações feitas com uma chave que não os possui falham com 403 Forbidden, independentemente da propriedade do recurso. Estes são escopos de administrador — somente administradores da organização podem adicioná-los a uma chave de API; portanto, se você não for administrador, precisará de uma chave emitida por um deles para seguir este guia. Consulte Escopos de chave de API obrigatórios para saber como habilitá-los.

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:
  1. No console, acesse Acesso → Chaves de API.
  2. Crie uma nova chave ou abra uma chave existente para editá-la.
  3. Na lista de escopos, localize a linha Autorização refinada e habilite ambas as caixas de seleção (leitura e gravação).
  4. Clique em Salvar.
O editor de escopos da chave de API com ambas as caixas de seleção de autorização refinada habilitadas e destacadas Para saber mais sobre a criação de chaves de API e o funcionamento dos escopos em geral, consulte o guia de introdução à plataforma.

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.
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:
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

Use POST /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:
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 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:
Como as funções são hierárquicas, um proprietário também passa em uma verificação de reader ou writer.

Revogar uma função

Use POST /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:
Uma revogação bem-sucedida retorna 204 No Content.

Conceder acesso público

Conceda uma função a todos os usuários autenticados definindo userId 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 retornam 403 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 chamador não é o proprietário do recurso. Somente proprietários podem conceder ou revogar:
Além de um problema real de permissões, esse erro tem duas causas comuns:
  • 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-Of está 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.
Sempre verifique a função do chamador antes de tentar alterações de permissão ou trate a resposta 403 na sua aplicação.

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