Permissões Granulares em Organizações

Permissões granulares controlam o que cada membro pode ver ou alterar dentro de uma organização. Elas aumentam a segurança porque reduzem acessos amplos e permitem liberar somente as ações necessárias para cada pessoa.

Na prática, você pode permitir que um usuário visualize apenas um projeto, consulte logs sem alterar configurações, acione deploys sem acessar cobrança ou gerencie pagamentos sem tocar em variáveis de ambiente.

Modelo de acesso

O acesso combina quatro elementos:

Elemento	Função
Papel	Define o nível base do membro: `owner`, `assistant` ou `member`
Recurso	Define a área afetada, como organização, projeto, template, banco, serviço gerenciado, cobrança, chave de IA ou API key global
Ação	Define a operação permitida, como ler logs, alterar ambiente ou criar checkout
Política reutilizável	Conjunto nomeado de permissões que pode ser vinculado a vários membros

O owner tem acesso completo à organização e ignora os checks granulares. Para assistant e member, o acesso é negado por padrão: a permissão efetiva é a união das permissões diretas do membro com as permissões das políticas vinculadas a ele.

Ao convidar um assistant, a Zenifra aplica um modelo inicial com operação de projetos, bancos, serviços gerenciados e chaves de IA, além de convidar membros e ajustar permissões. Esse modelo não inclui cobrança, API Keys, templates nem dados de visitantes. Um member começa sem permissões.

As permissões efetivas são calculadas a cada requisição, a partir das permissões diretas e das políticas ativas do membro. Elas nunca são copiadas para o membro: por isso, editar ou remover uma política altera o acesso de fato, inclusive para quem já criou recursos com ela.

Recursos protegidos

As permissões podem ser aplicadas a diferentes recursos da organização.

Recurso	Exemplos de acesso
organization	Criar projetos, templates, bancos, serviços gerenciados, chaves de IA e API Keys; convidar membros; alterar permissões
project	Ver projeto, logs, métricas, dados de visitantes, custos, variáveis, domínio, rede, instâncias, imagem, origem Git, deploys e ambientes de Preview
template	Ver, editar, publicar e remover templates da organização
database	Ver status, acessar conexão, rotacionar senha e atualizar versão
managed_service	Operar serviços gerenciados Valkey (Key-Value, Cache e Queue)
ai_key	Visualizar, alterar e excluir chaves e consultar uso e custos de IA
api_key	Visualizar e revogar API keys globais da organização
billing	Consultar cobrança, transações, checkout e métodos de pagamento

Algumas permissões são sensíveis e devem ser concedidas com cuidado. Acesso a variáveis de ambiente, conexão de banco, cobrança e alteração de deploy pode impactar operação, segurança ou custos.

Dados de visitantes

O IP de origem e o user agent de cada requisição recebida pela aplicação são dados pessoais dos visitantes. Por isso, eles exigem a permissão project.network.visitors.read no projeto, separada de project.metrics.read. Somente o owner tem esse acesso por padrão: ele não faz parte do modelo inicial de assistant, dos grants recebidos ao criar um projeto nem das conexões de assistentes de IA via MCP.

Permissão	O que libera nas métricas de rede
`project.metrics.read`	Resumo, códigos de status, rotas e user agents agregados por volume, sem vínculo com um visitante específico
`project.network.visitors.read`	Eventos individuais de requisição (com IP de origem e user agent) e a lista de IPs de origem com maior volume

Quem tem apenas project.metrics.read recebe 403 nas consultas de eventos de requisição e de IPs de origem; os dados não são mascarados, a consulta inteira é recusada. Veja Métricas de Rede.

Dados da organização

Os dados cadastrais e financeiros da organização, como documento, razão social, configuração de pagamento, situação de cobrança e saldo, só aparecem para quem tem billing.read em billing:*.

Escopo por recurso

Permissões podem ser concedidas para todos os recursos de um tipo ou para um recurso específico. Por exemplo, um membro pode receber acesso somente ao projeto de homologação, sem visualizar projetos de produção.

Exemplos:

acesso a logs e métricas de um único projeto;
permissão para atualizar imagem de todos os projetos de uma organização;
permissão para consultar conexão de um banco específico;
permissão para revogar uma API key global específica;
acesso de leitura à cobrança sem permissão para configurar pagamento;
autorização para acionar deploy a partir do repositório Git sem alterar a origem configurada.

Esse escopo evita que pessoas com responsabilidades limitadas tenham visibilidade ou controle sobre recursos que não fazem parte do trabalho delas.

API Keys da organização usam os mesmos scopes de recursos; as rotas de administração de membros, convites e políticas aceitam apenas sessão de usuário. O catálogo operacional completo, incluindo o escopo por ID e os endpoints representativos, está em API Keys da Organização. Scopes de criação são concedidos em organization:*; ações sobre um recurso devem preferir o ID específico.

Políticas reutilizáveis

Políticas reutilizáveis evitam repetir a mesma configuração em vários membros. Na página Membros, crie uma política com nome, descrição opcional e permissões, e vincule-a a convites ou membros existentes. As mesmas políticas também podem ser usadas como base ao criar uma API Key.

um membro pode ter várias políticas, além de permissões diretas;
editar uma política altera automaticamente a permissão efetiva de todos os membros vinculados;
remover uma política retira as permissões dela dos membros vinculados; acessos concedidos por outra política ou por permissão direta continuam valendo;
criar, editar e vincular políticas exige member.permissions.update em organization:*, e um assistant só pode vincular políticas a membros quando já possui todas as permissões contidas nelas;
editar ou remover uma política exige poder delegar todo o conteúdo dela, o atual e o novo; um assistant não pode editar nem remover uma política vinculada a um owner ou a outro assistant (403).

Quem pode delegar

Somente o owner e o assistant delegam permissões. O owner pode conceder qualquer permissão a assistant e member. O assistant só concede permissões e políticas que ele mesmo possui, e somente para pessoas com papel member; tentativas fora dessa regra respondem 403. Um member com member.invite ou member.permissions.update consegue consultar membros e políticas, mas não convida nem altera permissões.

As requisições que enviam permissões (criar ou editar políticas, criar API Keys, convidar membros e alterar as permissões diretas de um membro) aceitam corpo de até 64 KB, o suficiente para grants explícitos em muitos recursos.

Grants ao criar recursos

Quando alguém que não é owner cria um recurso, a Zenifra acrescenta às permissões diretas dessa pessoa apenas os grants daquele recurso novo:

Recurso criado	Grants recebidos no recurso novo
Aplicação HTTP ou Job agendado	Operação do projeto: leitura, logs, métricas, variáveis, nome, descrição, domínio, rede, instâncias, imagem, origem Git, agendamento, execuções, deploy, parar, retomar, plano, armazenamento e remoção
Banco de dados	Os mesmos grants de projeto, mais status, conexão, rotação de senha e atualização de versão do banco
Serviço Valkey	Os mesmos grants de projeto, mais as ações de `managed_service` do serviço
Template	`template.read`, `template.update` e `template.delete`; publicar exige `template.publish` concedido separadamente
Chave de IA	Leitura, alteração, remoção e consulta de uso da chave
API Key	Leitura, edição e revogação da chave

Os grants de projeto não incluem custos (project.billing.read) nem dados de visitantes (project.network.visitors.read). Projetos criados por API Key recebem grants próprios, descritos em API Keys da Organização.

Efeitos nas chaves do membro

Mudanças de acesso valem também para as chaves que o membro criou:

Mudança	Chaves de IA do membro	API Keys criadas pelo membro
Remover o membro ou o membro excluir a conta	Revogadas	Revogadas
Mudar o papel	Revogadas se ele deixar de ter `ai_key.create`	Passam a valer só o que ele ainda pode fazer
Alterar permissões diretas ou políticas vinculadas	Revogadas se ele deixar de ter `ai_key.create`	Passam a valer só o que ele ainda pode fazer
Editar ou remover uma política vinculada a ele	Revogadas se ele deixar de ter `ai_key.create`	Passam a valer só o que ele ainda pode fazer
Transferir a propriedade (antigo `owner`)	Revogadas	Ficam sem acesso até ele receber permissões

Ao mudar o papel, as permissões do membro voltam ao modelo inicial do novo papel e as políticas vinculadas são removidas. A revogação acontece antes de a mudança ser gravada: se a revogação das chaves de IA não puder ser confirmada, nada é alterado e a API responde 503 com a mensagem organization member credentials could not be revoked. Tente novamente em instantes.

Papéis recomendados

Use papéis como ponto de partida e ajuste permissões conforme a necessidade.

Perfil	Configuração recomendada
Fundador ou administrador principal	`owner`, com revisão periódica dos membros
Líder técnico	`assistant`, com acesso operacional aos projetos necessários
Desenvolvedor de um serviço	`member`, com acesso ao projeto específico, logs, métricas e deploy
Analista financeiro	`member`, com leitura de billing e transações
Suporte	`member`, com leitura de logs e métricas, sem alteração de ambiente

Evite transformar todos os colaboradores em assistant. Quanto mais amplo o papel, maior o impacto de erro humano, credenciais comprometidas ou alterações não planejadas.

Exemplos práticos

Desenvolvedor com acesso a um projeto

Conceda leitura do projeto, logs, métricas e deploy apenas no recurso específico. Se a pessoa também precisa alterar variáveis de ambiente, adicione essa ação explicitamente.

Responsável por cobrança

Conceda leitura de billing e transações. Só permita configurar pagamento ou criar checkout quando a pessoa realmente for responsável por métodos de pagamento.

Operador de banco

Conceda status e conexão do banco específico. Rotação de senha e atualização de versão devem ficar restritas a pessoas autorizadas.

Transferência de propriedade

Cada organização tem um único owner. Somente ele pode alterar papéis, remover membros e transferir a propriedade da organização para outro membro ativo. Na transferência, o antigo owner passa a ser member sem permissões; se ele ainda precisar de acesso, o novo owner deve conceder as permissões necessárias. Hoje a transferência é feita pela API, em PATCH /v1/organizations/{id}/ownership, informando o user_id do novo owner com uma sessão de usuário.

As chaves de IA do antigo owner são revogadas na transferência, e as API Keys criadas por ele ficam sem acesso até que ele receba permissões novamente. Antes de transferir, recrie as chaves usadas por automações críticas com o novo owner ou com um membro dedicado.

Código	Motivo
`404`	O `user_id` informado não é um membro ativo da organização
`409`	O `user_id` é o do próprio `owner` (`organization owner cannot transfer ownership to themselves`) ou a transferência não pôde ser concluída
`503`	As chaves de IA do antigo `owner` não puderam ser revogadas; nada foi alterado

Boas práticas de segurança

aplique o princípio do menor privilégio;
prefira acesso por projeto em ambientes críticos;
revise permissões quando uma pessoa muda de função;
remova membros que não participam mais da organização;
limite acesso a billing, segredos e configuração de deploy;
use contas individuais, nunca credenciais compartilhadas.

Permissões granulares são mais eficazes quando fazem parte de uma rotina de governança. Revise membros e permissões em intervalos definidos, principalmente em organizações com produção, dados sensíveis ou custos relevantes.