O controle de acesso baseado em funções (RBAC) permite definir quem pode fazer o quê na sua organização e nos seus projetos, tanto pela API quanto pelo painel. As mesmas permissões se aplicam às duas interfaces: se alguém pode chamar um endpoint (por exemplo, /v1/chat/completions), também pode usar a página correspondente no painel. A ausência de permissões desativa os elementos relacionados da interface, como o botão Enviar no Playground. Com o RBAC, você pode:
- Agrupar usuários e atribuir permissões em escala
- Criar funções personalizadas com exatamente as permissões de que você precisa
- Definir o escopo de acesso no nível da organização ou do projeto
- Aplicar permissões consistentes no painel e na API
Conceitos fundamentais
- Organização: sua conta de nível mais alto. As funções da organização podem conceder acesso a todos os projetos.
- Projeto: um workspace para chaves, arquivos e recursos. As funções do projeto concedem acesso somente dentro desse projeto.
- Grupos: conjuntos de usuários aos quais você pode atribuir funções. Os grupos podem ser sincronizados a partir do seu provedor de identidade (via SCIM) para manter a lista de membros atualizada automaticamente.
- Funções: conjuntos de permissões (como Requisição a modelos ou Gravação de arquivos). É possível criar funções para a organização em Configurações da organização ou para um projeto específico nas configurações desse projeto. Depois de criadas, as funções da organização ou do projeto podem ser atribuídas a usuários ou grupos. Os usuários podem ter várias funções, e seu acesso corresponde à união delas.
- Permissões: as ações específicas que uma função permite (por exemplo, fazer requisições a modelos, ler arquivos, gravar arquivos e gerenciar chaves).
Permissões
A tabela abaixo mostra as permissões disponíveis, quais funções predefinidas as incluem e se elas podem ser configuradas em funções personalizadas.
| Área | O que permite | Permissões do proprietário da organização | Permissões do leitor da organização | Permissões do proprietário do projeto | Permissões do membro do projeto | Permissões do visualizador do projeto | Disponível para funções personalizadas |
|---|---|---|---|---|---|---|---|
| Listar modelos | Listar os modelos aos quais esta organização tem acesso | Read | Read | Read | Read | Read | ✓ |
| Grupos | Visualizar e gerenciar grupos | Read, Write | Read | Read, Write | Read, Write | Read | |
| Funções | Visualizar e gerenciar funções | Read, Write | Read | Read, Write | Read, Write | Read | |
| Administração da organização | Gerenciar usuários, projetos, convites, chaves da API de administração e limites de taxa da organização | Read, Write | |||||
| Uso | Visualizar o painel de uso e exportar dados | Read | ✓ | ||||
| Chaves externas | Visualizar e gerenciar chaves do Enterprise Key Management | Read, Write | |||||
| Lista de IPs permitidos | Visualizar e gerenciar a lista de IPs permitidos | Read, Write | |||||
| mTLS | Visualizar e gerenciar as configurações de TLS mútuo | Read, Write | |||||
| OIDC | Visualizar e gerenciar a configuração de OIDC | Read, Write | |||||
| Capacidades dos modelos | Fazer requisições a chat completions, áudio, embeddings e imagens | Request | Request | Request | Request | ✓ | |
| Assistentes | Criar e recuperar assistentes | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Threads | Criar e recuperar Threads/Messages/Runs | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Avaliações | Criar, recuperar e excluir avaliações | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Ajuste fino | Criar e recuperar tarefas de ajuste fino | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Arquivos | Criar e recuperar arquivos | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Armazenamentos vetoriais | Criar e recuperar armazenamentos vetoriais | Read, Write | Read, Write | Read, Write | Read, Write | ✓ | |
| Responses API | Criar respostas | Read, Write | Read, Write | Read, Write | Read, Write | ✓ | |
| Prompts | Criar e recuperar prompts para usar como contexto na Responses API e na Realtime API | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Webhooks | Criar e visualizar webhooks no seu projeto | Read, Write | Read | Read, Write | Read, Write | Read | ✓ |
| Conjuntos de dados | Criar e recuperar conjuntos de dados | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Apps | Criar, gerenciar e enviar aplicativos para revisão no Painel | Read, Write | ✓ | ||||
| Túneis | Inspecionar, usar e gerenciar túneis com escopo de organização | Read, Use, Manage | ✓ | ||||
| Chaves de API do projeto | Permissão para um usuário gerenciar suas próprias chaves de API | Read, Write | Read, Write | Read, Write | Read, Write | Read | ✓ |
| Administração do projeto | Gerenciar usuários, contas de serviço, chaves de API e limites de taxa do projeto pela API de gerenciamento | Read, Write | Read, Write | ||||
| Processamento em lote | Criar e gerenciar tarefas de processamento em lote | Read, Write | Read, Write | Read, Write | Read, Write | Read | |
| Contas de serviço | Visualizar e gerenciar contas de serviço do projeto | Read, Write | Read, Write | ||||
| Vídeos | Criar e recuperar vídeos | Read, Write | Read, Write | Read, Write | Read, Write | ||
| Vozes | Criar e recuperar vozes | Read, Write | Read, Write | Read, Write | Read, Write | Read | |
| Criador de agentes | Criar e gerenciar agentes e fluxos de trabalho no Criador de agentes | Read, Write | Read | Read, Write | Read, Write | Read | ✓ |
Implicações das permissões de processamento em lote
As permissões de processamento em lote incluem o acesso necessário para preparar arquivos de entrada de lotes, executar requisições e recuperar resultados. Esse acesso efetivo é distinto dos endpoints que podem ser enviados em um lote, listados no guia da API de processamento em lote.
| Permissão de processamento em lote | Acesso adicional concedido |
|---|---|
Leitura (api.batch.read) | Leitura de arquivos (api.files.read) para /v1/files |
Escrita (api.batch.write) | Leitura de processamento em lote Listar modelos ( api.model.read e model.read) para /v1/modelsLeitura e escrita de arquivos ( api.files.read e api.files.write) para /v1/filesRequisições às capacidades dos modelos ( api.model.request e model.request) para /v1/audio, /v1/chat/completions, /v1/embeddings, /v1/images, /v1/moderations, /v1/realtime e /v1/responsesLeitura e escrita de vídeos ( api.videos.read e api.videos.write) para /v1/videos |
Configuração do RBAC
Aguarde até 30 minutos para que as alterações nas funções e a sincronização dos grupos sejam propagadas.
-
Crie grupos Adicione grupos para as equipes (por exemplo, “Ciência de dados”, “Suporte”). Se você usa um IdP, habilite a sincronização SCIM para manter atualizada a lista de membros dos grupos.
-
Crie funções personalizadas Comece com o menor privilégio possível. Por exemplo:
- Testador de modelos: Leitura de modelos, Requisições às capacidades dos modelos, Avaliações
- Engenheiro de modelos: Requisições às capacidades dos modelos, Leitura/escrita de arquivos, Ajuste fino
- Publicador de aplicativos: Leitura de Apps, Escrita de Apps
-
Atribua funções
- As funções no nível da organização se aplicam a todos os lugares (todos os projetos da organização).
- As funções no nível do projeto se aplicam apenas àquele projeto. Você pode atribuir funções a usuários e grupos. Os usuários podem ter várias funções; o acesso é a união delas.
-
Verifique Use uma conta sem a função de proprietário para confirmar o acesso esperado (API e Painel). Ajuste as funções se os usuários puderem ver mais do que precisam.
Use o princípio do menor privilégio. Comece com as permissões mínimas necessárias para uma tarefa e adicione outras apenas conforme necessário.
Exemplos de configuração de acesso
Equipe pequena
- Atribua à equipe principal uma função no nível da organização com as permissões de Solicitação de capacidades do modelo e Leitura/gravação de arquivos.
- Crie um projeto para cada aplicativo; adicione prestadores de serviços apenas a esses projetos, com funções no nível do projeto.
Organização maior
- Sincronize os grupos do seu IdP (por exemplo, “Pesquisa”, “Suporte”, “Finanças”).
- Crie funções personalizadas para cada área de atuação e atribua-as no nível da organização; ou conceda apenas funções específicas do projeto quando ele precisar de controles mais rigorosos.
Prestadores de serviços e fornecedores
- Crie um grupo “Prestadores de serviços” sem funções no nível da organização.
- Adicione-os a projetos específicos com funções de projeto de escopo restrito (por exemplo, acesso somente leitura).
Como o acesso do usuário é avaliado
No painel, combinamos:
- funções da organização (atribuídas diretamente + via grupos)
- funções do projeto (atribuídas diretamente + via grupos)
As permissões efetivas são a união de todas as funções atribuídas.
Ao receber uma requisição com uma chave de API de um projeto, consideramos as permissões atribuídas à chave de API e verificamos se o usuário tem alguma função no projeto que lhe conceda essas permissões. Por exemplo, em uma requisição a /v1/models, a chave de API deve ter a permissão api.model.read atribuída, e o usuário deve ter uma função no projeto com api.model.read.
Práticas recomendadas
- Represente sua organização em grupos: Reproduza a estrutura das equipes no seu IdP e atribua funções a grupos, não a indivíduos.
- Separe as responsabilidades: leitura de modelos, upload de arquivos e gerenciamento de chaves.
- Limites dos projetos: mantenha experimentos, homologação e produção em projetos separados.
- Revise regularmente: remova funções e chaves não utilizadas; faça a rotação de chaves sensíveis.
- Teste sem a função de proprietário: confirme se o acesso corresponde ao esperado antes de uma implementação em larga escala.