Funções e permissões dos membros

Toda pessoa convidada para uma organização Chargefy recebe uma função (role) que define o que ela pode fazer no dashboard. Essa página descreve as sete funções disponíveis, o que cada uma libera, como elas interagem com plataformas (sub-organizações) e como gerenciar tudo isso na tela de membros.

​

As sete funções

​

Matriz de capabilities

Cada ação interna do dashboard é amarrada a uma capability (uma chave curta como refund.create). A função do membro define quais capabilities ela tem.

​

Gerenciar membros e funções

A tela vive em Settings → Membros dentro de qualquer organização. Os controles — convidar, trocar função, revogar acesso — aparecem só para quem tem member.manage (Owner, Administrator e IAM admin). Para os demais, ficam ocultos.

​

Hierarquia estrita

Ter member.manage não dá poder sobre qualquer um. Vale uma regra de precedência estrita, na ordem owner > administrator > iam_admin > developer = support_specialist = analyst = view_only:

• Você só gerencia (troca função ou revoga) quem está estritamente abaixo de você. Um Administrator gerencia IAM admin e tudo abaixo — mas não outro Administrator, nem um Owner. Um IAM admin gerencia Developer, Support specialist, Analyst e View only.
• Owners são a exceção: são peers no topo. Um Owner pode gerenciar qualquer um, incluindo outros owners — promover, rebaixar ou revogar. E só um Owner pode conceder a função Owner (promovendo um membro ou convidando direto como Owner).
• Você só concede funções abaixo da sua (owners concedem qualquer uma). Por isso só um Owner cria ou promove alguém a Administrator. Um Administrator concede IAM admin e abaixo; um IAM admin, apenas Developer/Support/Analyst/View only.
• Último owner protegido. Não dá para rebaixar nem remover o último Owner ativo — promova outro a Owner antes.
• Você mesmo. Pode sair da organização quando quiser (a menos que seja o último Owner — promova outro antes), mas não altera a própria função.

A tela reflete isso automaticamente: as funções que você não pode conceder não aparecem no seletor, e o menu … some para membros que você não pode gerenciar — não fica um botão desabilitado nem um erro genérico. E não é só estética: o servidor aplica exatamente a mesma regra (veja abaixo).

​

Operações

• Convidar alguém. Clique em Convidar membro, informe o e-mail e escolha a função (só as que você pode conceder aparecem). View only é o padrão sugerido — princípio do menor privilégio.
• Trocar a função de quem já é membro. No menu … ao lado da pessoa, escolha Mudar para …. A mudança vale imediatamente.
• Remover um membro. Mesmo menu, Revogar acesso. A pessoa perde acesso na hora.

​

Herança em plataformas

Se sua organização é uma plataforma com sub-organizações conectadas (via platform_organizations), a função na organização-mãe é herdada nas organizações filhas conectadas e ativas. A resolução pega a função efetiva mais alta quando o usuário tem vínculo direto na filha e vínculo herdado da mãe. Ordem de prioridade: owner > administrator > iam_admin > developer > support_specialist > analyst > view_only.

​

Como a negação acontece

Quando um membro tenta executar uma ação que sua função não permite, dois mecanismos atuam:

1. No dashboard (UX otimista) — botões e ações cujo nível ela não tem ficam desabilitados com tooltip explicando o motivo (ex.: “Requires admin role”), ou são ocultados quando não fazem sentido (ex.: aba Customers para IAM admin) ou quando a hierarquia não permite (ações sobre alguém de função igual ou superior à sua). É só uma dica visual — a verdade está no servidor.
2. No backend (autoridade) — toda rota de mutação verifica a capability na API antes de executar. Negação retorna HTTP 403 com error.type = "authentication_error" e mensagem contendo a capability requerida (ex.: Access denied — required capability: refund.create).

Para o gerenciamento de membros, o backend vai além da capability e aplica a hierarquia estrita. Convidar, trocar função e revogar acesso passam por endpoints dedicados que comparam a sua função com a do alvo (e com a função sendo concedida) e devolvem HTTP 403 com mensagem específica, nunca um erro genérico:

• Tentar revogar/alterar alguém de função igual ou superior → Você não pode alterar a função de Administrator — exige permissão superior à sua.
• Tentar conceder uma função igual ou superior à sua → Você não pode conceder a função Administrator — ela é igual ou superior à sua.
• Tentar rebaixar/remover o último Owner → Não é possível rebaixar o único Owner — promova outro membro a Owner primeiro.

Por isso, mesmo que alguém chame a API diretamente (fora do dashboard), a regra de hierarquia continua valendo. A verificação acontece em duas camadas:

• Edge Functions (rotas de escrita) chamam o helper requireCapabilityIfJwt — aplica para JWT, ignora para API key (que tem o escopo próprio).
• Postgres / RLS — a maioria das tabelas de dados de pagamento têm policies que também checam user_has_capability(org_id, 'business.read'), fechando a porta caso alguma rota futura esqueça de gatear. É como o IAM admin acaba sem ver Customers/Charges/Subscriptions.

​

Diferença entre função e escopo de API key

Os dois são independentes. Um Support specialist pode criar uma cobrança via dashboard usando sua função, ou seu backend pode fazer o mesmo via API key com escopo write — são caminhos paralelos para o mesmo recurso.

​

Próximos passos

• Autenticação — JWT do dashboard vs API key da integração.
• Chaves de API — escopos, ambientes (live / test) e rotação.