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

# Admins e chaves API

> Convide admins e crie chaves API limitadas às partes do workspace de que precisam, mude as permissões a qualquer momento e veja o que cada permissão permite.

![Configurações, Equipe e chaves API: os membros, um convite pendente e duas chaves API](https://www.notifuse.com/docs/assets/screenshots/api_key.png)

## Gestão de admins

### Convidar admins

- Só o proprietário do workspace pode convidar novos admins.
- Você escolhe as permissões que o convite concede e pode mudá-las depois.
- Os convites são enviados por email.

O proprietário tem todas as permissões e não pode ser restringido. Todos os outros, admins humanos e chaves API, têm um conjunto de permissões escolhido por você.

### Permissões

> [!NOTE]
>
> **Em instalações auto-hospedadas, salvar um conjunto de permissões que não seja acesso total exige uma [chave de licença](https://www.notifuse.com/pt/docs/self-hosting/licence.md).** Isso vale para definir as permissões de um membro, convidar com um conjunto restrito e criar uma chave API com escopo restrito. Sem a chave de licença, novos membros e novas chaves recebem acesso total. As permissões já concedidas continuam valendo em qualquer estado da licença, e remover um membro é sempre permitido, porque é assim que se revoga uma chave vazada. O Notifuse Cloud inclui permissões granulares a partir do plano Starter ([detalhes](https://www.notifuse.com/pt/docs/self-hosting/licence.md#on-notifuse-cloud)).

Uma permissão é um par de interruptores sobre uma área do workspace: **leitura** e **escrita**. A escrita não implica a leitura, e os dois ficam desligados até serem concedidos. A barra lateral do console mostra uma seção quando o membro tem qualquer um dos dois interruptores na área dela.

Você pode mudar as permissões de um membro na página Equipe e chaves API a qualquer momento. A mudança vale a partir da próxima requisição dele.

## Gestão de chaves API

### Criar chaves API

- Só o proprietário do workspace pode criar uma chave API.
- Você escolhe as permissões da chave ao criá-la, ou concede tudo.
- O token aparece uma única vez, quando a chave é criada.

![As permissões de uma chave API, com interruptores de leitura e escrita para cada recurso](https://www.notifuse.com/docs/assets/screenshots/api_key_permissions.png)

Uma chave criada sem nenhuma escolha de permissão tem acesso total ao workspace. As chaves criadas antes das permissões com escopo se comportam da mesma forma até você restringi-las.

Uma chave criada com todas as permissões desligadas ainda consegue se autenticar e chegar aos poucos endpoints que nenhuma permissão controla: `/api/workspaces.list` retorna o registro do workspace ao qual a chave pertence (as configurações, os rótulos dos campos personalizados e os blocos de template reutilizáveis guardados nele), com as credenciais dos provedores ocultadas. Tudo o que aparece na tabela abaixo fica fechado para ela.

Dê a cada integração a sua própria chave, com as permissões mínimas de que ela precisa. Uma chave que só envia emails transacionais precisa apenas da escrita de Transacional (veja [API transacional](https://www.notifuse.com/pt/docs/features/transactional-api.md)). O [Zapier](https://www.notifuse.com/pt/docs/integrations/zapier.md) define o próprio escopo: conectá-lo em **Configurações** → **Integrações** cria uma chave com leitura e escrita de Assinaturas de Webhook, Contatos e Listas, mais a leitura de Segmentos.

O prefixo que você escolhe vira o endereço de email da chave na API e o nome de usuário dela na ponte SMTP. Ele aceita letras minúsculas, dígitos, hífens e sublinhados, até 64 caracteres, e só pode ser usado uma vez por instalação do Notifuse.

### Mudar o escopo de uma chave

Você pode ampliar ou restringir uma chave existente a qualquer momento na página Equipe e chaves API. A mudança vale a partir da próxima requisição da chave. **O token não muda**, então não há nada a emitir de novo nem integração a atualizar.

### Segurança

- Copie e guarde o token assim que a chave for criada.
- Um token perdido não pode ser recuperado: crie uma nova chave.
- Todas as chamadas à API devem usar HTTPS.

Quando uma chave é recusada, a API responde `403` e indica a área que falta (`contacts`, `webhook_subscriptions` etc.) e o interruptor que falta. Um `403` de cota não traz nenhum dos dois, então é fácil distinguir os casos.

## Revogar uma chave

> [!WARNING]
>
> Remover a chave é a única forma de revogá-la, e a operação é destrutiva: o token continua válido até
> a chave ser removida, e uma chave removida não pode ser restaurada nem emitida de novo. Toda
> integração que a usa para de funcionar no momento em que você a remove.

Saiba estes dois pontos antes de um incidente:

- **Restringir uma chave não a revoga.** Uma chave sem nenhuma permissão ainda se autentica e mantém o acesso que nenhuma permissão controla. Restringir serve para conter uma chave, não para eliminá-la.
- **Não dá para saber qual chave vazou.** As chaves não registram a data do último uso nem têm log de requisições próprio. Se você suspeita que um token foi exposto mas não tem o token em mãos, o Notifuse não consegue dizer qual chave é. Com várias chaves em uso, a única resposta segura é remover todas, criar substitutas e atualizar todas as integrações.

Nem sempre a chave é removida pela página Equipe e chaves API: excluir uma conexão do [Zapier](https://www.notifuse.com/pt/docs/integrations/zapier.md) em **Configurações** → **Integrações** remove a chave que ela criou, e excluir um workspace remove todas as chaves dele. Remover a chave de uma conexão do Zapier em Equipe e chaves API também a revoga, mas deixa o cartão da conexão no lugar, apontando para uma chave que não existe mais.

Por isso, tenha poucas chaves, dê a cada uma um prefixo com o nome do sistema que a usa e prefira chaves restritas, para que um vazamento custe uma integração, e não o workspace inteiro.

## O que cada permissão permite

> [!NOTE]
>
> Quando uma versão traz uma nova permissão, os membros e as chaves API existentes a recebem na
> atualização. Uma chave que você restringiu de propósito, portanto, ganha a nova área e fica assim
> até você restringi-la de novo. Revise as suas chaves com escopo depois de cada atualização. Uma chave
> com _todas_ as permissões desligadas é uma exceção: a atualização não mexe nela.
>
> **A leitura de Logs de auditoria é a segunda exceção**, e a única permissão que funciona assim: ela
> nunca é preenchida na atualização e não faz parte do acesso total. Conceda-a apenas às pessoas e às
> chaves que devem ler o endereço de email, o endereço IP e as ações recusadas de cada colega.

No console, clique no nome de uma permissão na matriz para ver os endpoints que ela controla e o que cada um faz. A tabela abaixo resume tudo.

| Permissão                  | A leitura permite                                                                                                                                                                                                                                                                            | A escrita permite                                                                                                                                                                                                                                     |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contatos**               | Ver os contatos e os perfis completos deles, a timeline e os eventos personalizados registrados para eles. Também é necessária para listar os endereços de uma lista ou de um segmento e para definir `cc` ou `bcc` em um envio transacional                                                 | Criar e atualizar contatos, **excluí-los**, **sobrescrever todos os campos em massa** por uma importação CSV ou pela API, e registrar eventos personalizados                                                                                          |
| **Segmentos**              | Ver os segmentos, as definições deles e o estado das tarefas de construção. Visualizar um segmento, ou listar os contatos que ele seleciona, também exige a leitura de Contatos                                                                                                              | Criar, editar, excluir e reconstruir segmentos, e executar, reiniciar ou excluir as tarefas de construção deles                                                                                                                                       |
| **Listas**                 | Ver as listas, as configurações e o número de inscritos. Listar os membros de uma lista também exige a leitura de Contatos                                                                                                                                                                   | Criar, editar e excluir listas, e **inscrever um endereço em qualquer lista, pública ou não, o que cria ou sobrescreve o registro desse contato na mesma chamada**. Mudar ou remover uma inscrição existente também exige a escrita de Contatos       |
| **Templates**              | Ver os templates em todos os idiomas e os blocos de template reutilizáveis, e compilar um template com dados de teste. Junto com a escrita de Transacional, também é necessária para enviar um email de teste e para criar ou editar uma notificação transacional                            | Criar, editar e excluir templates e blocos reutilizáveis. Editar um bloco não altera os templates que já o contêm                                                                                                                                     |
| **Blog**                   | Ver as categorias, os posts, incluindo os rascunhos não publicados, e as versões do tema, incluindo os scripts                                                                                                                                                                               | Criar, editar, excluir, publicar e despublicar posts e categorias; **publicar um tema**; e mudar as configurações do blog, inclusive ligá-lo ou desligá-lo                                                                                            |
| **Broadcasts**             | Ver os broadcasts, a configuração e os resultados de teste A/B deles, e o estado das tarefas de envio. As estatísticas de entrega ficam com a leitura de Histórico de Mensagens                                                                                                              | Criar e editar broadcasts, atualizar e testar feeds de dados, e agendar, **enviar para todo o público**, pausar, retomar, cancelar e excluir um broadcast, escolher o vencedor do teste A/B e executar ou reiniciar a tarefa de envio por trás dele   |
| **Transacional**           | Ver as definições das notificações transacionais                                                                                                                                                                                                                                             | Criar, editar e excluir essas notificações, e enviar emails reais: pela API, pela ponte SMTP e como teste de template. Testar um provedor de email continua com o proprietário. Veja [as regras de envio](#transactional-sending-and-contacts) abaixo |
| **Automacoes**             | Ver as automações, a configuração completa dos nós, incluindo as URLs e os segredos bearer dos nós de webhook, e a jornada de um contato específico em um fluxo                                                                                                                              | Criar, editar e excluir automações, e ativá-las ou pausá-las                                                                                                                                                                                          |
| **Histórico de Mensagens** | Ver as mensagens enviadas, com os endereços dos destinatários e os dados renderizados, e as contagens de entregas, aberturas, cliques, retornos e cliques por link de um broadcast                                                                                                           | **Nada: este verbo não controla nada hoje**                                                                                                                                                                                                           |
| **Web Analytics**          | Ver as análises do site, as anotações desenhadas nesses gráficos e o progresso da importação de histórico                                                                                                                                                                                    | Criar, editar e excluir anotações, iniciar e cancelar a importação do histórico, e mudar as configurações de web analytics (domínios permitidos, filtros, rótulos das dimensões personalizadas e identificação pelos links de email)                  |
| **Assinaturas de Webhook** | Listar as assinaturas e abrir cada uma, e ler o log de entregas, incluindo o payload de cada evento e a resposta do endpoint. O segredo de assinatura fica oculto para todos, menos para o proprietário                                                                                      | Criar, editar, excluir, ativar e desativar assinaturas, e disparar uma entrega de teste                                                                                                                                                               |
| **Eventos de Webhook**     | Ver os callbacks brutos que os seus provedores de email enviam de volta, incluindo os endereços dos destinatários e os diagnósticos do provedor                                                                                                                                              | **Nada: este verbo não controla nada hoje**                                                                                                                                                                                                           |
| **Logs de auditoria**      | Ler a [trilha de auditoria](https://www.notifuse.com/pt/docs/features/audit-logs.md) e exportá-la: quem fez o quê no workspace, com o endereço de email de quem agiu, o endereço IP de onde veio e as ações que foram recusadas. **Nunca concedida pelo "acesso total"** (veja a nota acima) | **Nada: este verbo não controla nada hoje.** A plataforma escreve os registros, e a retenção é uma configuração exclusiva do proprietário                                                                                                             |
| **LLM**                    | **Nada: este verbo não controla nada hoje**                                                                                                                                                                                                                                                  | Usar o assistente de IA                                                                                                                                                                                                                               |
| **Workspace**              | Ler o registro do workspace e as configurações dele, e ver toda a equipe: membros, proprietários, chaves API e convites pendentes. Sem ela, a lista da equipe mostra apenas a sua própria linha em vez de ser recusada                                                                       | Renomear os rótulos dos campos personalizados de contato do workspace, e executar, reiniciar ou excluir uma tarefa de sincronização de integração. **Nada além disso** (veja abaixo)                                                                  |

Duas famílias de endpoints são compartilhadas e verificam a permissão que corresponde à requisição: `/api/analytics.query` verifica a permissão de cada schema consultado, e `/api/tasks.*` verifica a permissão do tipo de tarefa (Segmentos para a construção de segmentos, Broadcasts para os envios, Web Analytics para as importações de histórico, Workspace para as sincronizações de integração).

### Verbos que não controlam nada hoje

Quatro interruptores não têm nenhum endpoint por trás na API atual: **leitura de LLM**, **escrita de Histórico de Mensagens**, **escrita de Eventos de Webhook** e **escrita de Logs de auditoria**. O console mostra os quatro concedidos e travados, e você não pode desligá-los.

Guardar um deles como "desligado" seria permanente: o preenchimento de uma permissão que falta só acrescenta o que uma concessão não tem. Nada o ligaria se uma versão futura desse ao verbo algo para controlar.

Concedê-los não dá nada, porque o trabalho acontece em outro lugar. O assistente de IA responde à escrita de LLM. O histórico de mensagens é somente leitura porque é o pipeline de envio que grava as linhas dele. Os callbacks dos provedores chegam por rotas que não têm sessão e não verificam permissão. A própria plataforma escreve a trilha de auditoria, e a única configuração editável da trilha, a retenção, é exclusiva do proprietário e não depende de nenhuma permissão.

### A escrita de Workspace é mais estreita do que parece

A única configuração do workspace que a permissão **Workspace** deixa mudar são os rótulos dos campos personalizados de contato. Ela **não** cobre:

- Renomear o workspace, mudar as configurações gerais dele ou excluí-lo: exclusivo do proprietário.
- Criar, atualizar ou excluir uma integração: exclusivo do proprietário. A escrita de Workspace não concede isso, e o proprietário tem esse direito sem ela.
- As configurações do blog, que dependem da escrita de Blog.
- As configurações de web analytics, que dependem da escrita de Web Analytics.

Assim, dar a alguém o blog ou a análise do site também lhe dá a configuração desse recurso no nível do workspace, incluindo o interruptor que liga ou desliga o recurso.

## Ações exclusivas do proprietário

Nenhuma permissão concede estas ações. Elas ficam com o proprietário do workspace, qualquer que seja o acesso de um membro ou de uma chave:

- Renomear o workspace, mudar as configurações gerais dele e excluí-lo
- Criar, atualizar e excluir integrações, e os endpoints de configuração do Amazon SES
- Registrar webhooks em um provedor de email, porque isso usa as credenciais do provedor guardadas na sua integração
- Testar um provedor de email, o que envia um email de teste com as credenciais do provedor guardadas na sua integração
- Gerar de novo o segredo de assinatura de uma assinatura de webhook, e lê-lo (ele fica oculto para todos os outros)
- Convidar um membro, remover um membro e definir as permissões de um membro
- Criar uma chave API
- Transferir a propriedade do workspace

## Permissões que vão além do nome

Leia estes pontos antes de concedê-las a uma chave que você não controla totalmente.

- **A escrita de Contatos exclui e sobrescreve em massa.** Ela cobre `/api/contacts.delete` e cobre `/api/contacts.import`, que sobrescreve todos os campos que cada linha traz: uma única chamada pode reescrever toda a sua base de contatos. Da mesma forma, a leitura de Contatos vai além dos perfis: ela cobre a timeline do contato e os eventos personalizados.
- **A escrita de Listas é uma escrita implícita de Contatos.** Inscrever um endereço por `/api/lists.subscribe` cria ou sobrescreve o registro inteiro desse contato com todos os campos que a requisição traz, **sem precisar da escrita de Contatos**. Assim, uma chave que só tem a escrita de Listas pode reescrever dados de contatos. A mesma chamada pode inscrever alguém em uma lista que não é pública. Conceda a escrita de Listas só onde você concederia a escrita de Contatos.
- **A escrita de Broadcasts envia.** O interruptor que permite a alguém preparar uma campanha também permite enviá-la para todo o seu público, por `/api/broadcasts.schedule` ou disparando ou reiniciando a tarefa de envio por trás dela.
- **A escrita de Automações lê contatos, muda listas e envia emails.** Um nó de webhook envia o registro completo do contato para qualquer URL que a automação indicar, e nada verifica permissões enquanto uma automação roda. Outros nós adicionam e removem contatos de listas e enviam emails. Esse interruptor alcança, portanto, os dados dos contatos, a participação nas listas e o envio, sem nenhuma concessão de Contatos, Listas ou Transacional.
- **A leitura de Automações expõe segredos.** A configuração dos nós de webhook que ela retorna inclui os tokens bearer definidos nesses nós.
- **A escrita de Blog executa JavaScript no seu domínio.** Ela inclui publicar um tema, cujo próprio `scripts.js` é servido a todos os visitantes do domínio personalizado do seu blog. Ela também liga e desliga o recurso de blog.
- **Templates cobre os blocos reutilizáveis.** Quem tem escrita de Templates pode editar, substituir ou excluir os blocos salvos do workspace. Os templates existentes mantêm a própria cópia, e as inserções futuras recebem o bloco atualizado. Os blocos ficam guardados com as configurações do próprio workspace, então o conteúdo deles também volta no registro do workspace.
- **Web Analytics cobre as anotações.** As anotações não têm permissão própria, então esta concessão também permite escrever na timeline compartilhada que todos leem. O coletor público de rastreamento não depende de nenhuma permissão: ele aceita dados sem autenticação.
- **A escrita de Assinaturas de Webhook recebe dados de contatos e de emails.** Uma assinatura escolhe os eventos que transmite, então quem tem a permissão pode assinar eventos de contato e de email e receber esses dados em qualquer URL. A leitura abre o log de entregas, que guarda os próprios payloads. Veja [Webhooks](https://www.notifuse.com/pt/docs/features/webhooks.md).
- **A leitura de Segmentos mais a leitura de Contatos é uma ferramenta de consulta.** `/api/segments.preview` aceita qualquer definição, não só um segmento salvo, então as duas juntas podem contar contatos por qualquer condição sobre atributos, participação em listas, eventos personalizados e timeline, uma contagem de cada vez. A leitura de Segmentos sozinha não pode.
- **A leitura de Histórico de Mensagens é dado de contato.** O log traz os endereços dos destinatários e os dados com que cada mensagem foi renderizada.
- **A escrita de LLM gera custos.** As requisições ao assistente de IA vão para o provedor de IA configurado, cobradas do seu workspace, sem limite por chave. Com uma integração Firecrawl configurada, ela também permite que o assistente faça scraping e buscas na web com as suas credenciais.

### Envio transacional e contatos

**A escrita de Transacional sozinha basta para enviar**, então uma chave só de envio é viável. As regras são as mesmas na API e na [ponte SMTP](https://www.notifuse.com/pt/docs/features/transactional-api.md):

- **Sem a escrita de Contatos**, o envio ainda cria o contato destinatário quando ele não existe, mas não guarda nada além do endereço de email e nunca modifica um contato existente.
- **Sem a leitura de Contatos**, um envio que define `cc` ou `bcc` é recusado, porque a linha de assunto é renderizada com o registro completo de cada destinatário. Na ponte SMTP, esses valores vêm dos cabeçalhos `Cc:` e `Bcc:` da mensagem.

A escrita de Transacional envia emails reais por dois endpoints, `/api/transactional.send` e `/api/transactional.testTemplate`, e pela ponte SMTP. Testar um provedor de email (`/api/email.testProvider`) é reservado ao proprietário do workspace, assim como criar e editar integrações, quaisquer que sejam as permissões da chave.

Um email de teste (`/api/transactional.testTemplate`) também exige a leitura de Templates, porque lê o template com as suas próprias permissões, e a leitura de Listas quando é enviado para uma lista de emails. Criar uma notificação transacional também exige a leitura de Templates, assim como editá-la com os `channels`, que o console envia ao editar uma notificação que nenhuma integração gerencia.
