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 nem templates. Um member começa sem permissões.

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

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.

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.

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.