> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Funções e permissões dos membros

> Quais ações cada membro da organização pode executar no dashboard — Owner, Administrator, IAM admin, Developer, Support specialist, Analyst e View only. Diferente de API keys; vale só para usuários logados em dashboard.chargefy.io.

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.

<Info>
  **Funções valem para usuários logados em `dashboard.chargefy.io`** — autenticação por JWT. Integrações server-to-server usam **API keys** com escopo próprio (`read` / `write` / `admin`) e não passam por essa permissão. Para detalhes da autenticação programática, veja [Autenticação](/integrate/authentication) e [Chaves de API](/integrate/api-keys).
</Info>

## As sete funções

| Função                 | Quem deveria ter                                                          | Resumo                                                                                                                                                        |
| ---------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**              | Donos da conta                                                            | Acesso total, incluindo deletar a organização. Uma organização pode ter **vários** owners.                                                                    |
| **Administrator**      | Lideranças que gerenciam dia-a-dia                                        | Acesso quase total. Pode tudo que o Owner pode, exceto deletar a organização.                                                                                 |
| **IAM admin**          | Time de TI / acesso responsável por convidar e remover pessoas            | Gerencia membros e suas funções. **Não acessa dados de pagamento** (customers, charges, subs, etc.).                                                          |
| **Developer**          | Engenheiros que mantêm a integração                                       | API keys, webhooks, dev tools (logs, events). Lê dados de negócio para debug, mas não executa ações de negócio (não faz refund, não edita customer).          |
| **Support specialist** | Atendimento ao cliente                                                    | Customer, refund, dispute, subscription, e **pode criar pagamentos** (checkout sessions, payment links, payment intents) para um cliente. Sem dev/financeiro. |
| **Analyst**            | Operação que reage a casos pontuais                                       | Refund, dispute, customer edit, cancelar/pausar assinatura. **Não cria pagamentos novos** — reage a dados existentes.                                         |
| **View only**          | Stakeholders que só precisam ver dados (financeiro, analytics, auditoria) | Lê tudo. Não executa nenhuma ação de escrita.                                                                                                                 |

<Note>
  **Uma organização pode ter vários owners.** Quem **cria** a organização entra como o primeiro Owner. A partir daí, qualquer Owner pode promover outro membro a Owner ou convidar alguém diretamente como Owner — owners são peers no topo e podem gerenciar uns aos outros. A única trava é o **último owner**: não dá para remover nem rebaixar o último Owner ativo, para a organização nunca ficar sem ninguém com controle total.
</Note>

<Note>
  **`owner`/`admin`/`member` foram refeitos.** Se você tinha membros com a função antiga `admin`, eles foram migrados para **Administrator**. A pessoa mais antiga (criadora) de cada organização foi promovida automaticamente para **Owner**. Membros antigos com `support` viraram **Support specialist**; `read_only` virou **View only**. Promova ou rebaixe quem precisar na tela de membros.
</Note>

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

| Capability                                                                            | Owner | Admin | IAM | Dev | Support | Analyst | View |
| ------------------------------------------------------------------------------------- | :---: | :---: | :-: | :-: | :-----: | :-----: | :--: |
| `org.delete` — deletar a organização                                                  |   ✅   |   —   |  —  |  —  |    —    |    —    |   —  |
| `org.manage` — configurações da organização                                           |   ✅   |   ✅   |  —  |  —  |    —    |    —    |   —  |
| `member.manage` — convidar, remover, trocar função                                    |   ✅   |   ✅   |  ✅  |  —  |    —    |    —    |   —  |
| `api_key.manage` — criar e revogar API keys                                           |   ✅   |   ✅   |  —  |  ✅  |    —    |    —    |   —  |
| `api_key.read_secret` — visualizar o token cru                                        |   ✅   |   ✅   |  —  |  ✅  |    —    |    —    |   —  |
| `webhook.manage` — endpoints de webhook                                               |   ✅   |   ✅   |  —  |  ✅  |    —    |    —    |   —  |
| `dev_tools.view` — DevConsole, logs de eventos                                        |   ✅   |   ✅   |  —  |  ✅  |    —    |    —    |   —  |
| `payment_profile.manage` — KYC, contas bancárias, splits                              |   ✅   |   ✅   |  —  |  —  |    —    |    —    |   —  |
| `bank_account.read` — visualizar conta bancária                                       |   ✅   |   ✅   |  —  |  —  |    —    |    —    |   —  |
| `product.write` — criar/editar produtos e preços                                      |   ✅   |   ✅   |  —  |  —  |    —    |    —    |   —  |
| `discount.write` — criar/editar descontos e cupons                                    |   ✅   |   ✅   |  —  |  —  |    —    |    —    |   —  |
| `payment.create` — checkout sessions, payment intents, payment links                  |   ✅   |   ✅   |  —  |  —  |    ✅    |    —    |   —  |
| `customer.write` — criar/editar customers                                             |   ✅   |   ✅   |  —  |  —  |    ✅    |    ✅    |   —  |
| `subscription.write` — criar/atualizar/cancelar/pausar                                |   ✅   |   ✅   |  —  |  —  |    ✅    |    ✅    |   —  |
| `refund.create` — emitir reembolsos                                                   |   ✅   |   ✅   |  —  |  —  |    ✅    |    ✅    |   —  |
| `dispute.respond` — atualizar disputas e enviar evidência                             |   ✅   |   ✅   |  —  |  —  |    ✅    |    ✅    |   —  |
| `business.read` — ler customers, charges, subs, invoices, refunds, disputes, payments |   ✅   |   ✅   |  —  |  ✅  |    ✅    |    ✅    |   ✅  |

<Info>
  **IAM admin não tem `business.read`.** A tela do IAM admin esconde Customers, Subscriptions, Invoices, Payments, Refunds, Disputes — ele só vê Members e (no futuro) audit logs. Isso vale também na API: SELECT em qualquer tabela de dados de pagamento retorna vazio para IAM admin, mesmo em consulta direta.
</Info>

<Info>
  **Recursos sensíveis ficam fora do View only, Support e Analyst.** O *token* completo de uma chave de API só aparece para quem tem `api_key.read_secret` (Owner, Administrator, Developer). O mesmo vale para os dados da conta bancária. A listagem de chaves (nome + última utilização) continua visível para quem tem `api_key.manage`.
</Info>

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

| Sua função        | Pode gerenciar                                            | Pode conceder                                                |
| ----------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
| **Owner**         | todos, **incluindo outros owners** (menos o último owner) | qualquer função, incluindo Owner                             |
| **Administrator** | IAM admin e abaixo                                        | IAM admin, Developer, Support specialist, Analyst, View only |
| **IAM admin**     | Developer, Support specialist, Analyst, View only         | Developer, Support specialist, Analyst, View only            |

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.

| Você é, na organização-mãe… | …e na organização filha você se comporta como | Pode                                      |
| --------------------------- | --------------------------------------------- | ----------------------------------------- |
| **Owner**                   | Owner                                         | Tudo, incluindo deletar a sub-organização |
| **Administrator**           | Administrator                                 | Quase tudo (não deleta)                   |
| **IAM admin**               | IAM admin                                     | Só membros                                |
| **Developer**               | Developer                                     | API keys/webhooks/logs + leitura          |
| **Support specialist**      | Support specialist                            | Operacional de cliente                    |
| **Analyst**                 | Analyst                                       | Operacional sem criar pagamento           |
| **View only**               | View only                                     | Só leitura                                |

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

<Note>
  Não existe role específica de "platform admin" — quem é Administrator/Owner na organização-mãe age como tal nas filhas. Para acesso restrito de equipe a uma filha específica, convide a pessoa diretamente para a filha com a função apropriada.
</Note>

## 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

|                        | Função de membro                                                                                 | Escopo de API key                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| Atua em                | Sessão JWT do dashboard                                                                          | Requisições server-to-server com `Authorization: Bearer ch_...` |
| Valores                | `owner`, `administrator`, `iam_admin`, `developer`, `support_specialist`, `analyst`, `view_only` | `read`, `write`, `admin`                                        |
| Inheritance entre orgs | Sim — função na mãe vale na filha                                                                | Não — escopo da key vale só onde a key opera                    |
| Criada via             | Convite de membro                                                                                | Painel **Settings → Chaves de API**                             |

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](/integrate/authentication) — JWT do dashboard vs API key da integração.
* [Chaves de API](/integrate/api-keys) — escopos, ambientes (`live` / `test`) e rotação.