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
Nota
Em instalações auto-hospedadas, salvar um conjunto de permissões que não seja acesso total exige uma chave de licença. 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).
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.
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). O Zapier 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
Atenção
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 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
Nota
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 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 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.deletee 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.subscribecria 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.scheduleou 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.
- A leitura de Segmentos mais a leitura de Contatos é uma ferramenta de consulta.
/api/segments.previewaceita 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:
- 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
ccoubccé recusado, porque a linha de assunto é renderizada com o registro completo de cada destinatário. Na ponte SMTP, esses valores vêm dos cabeçalhosCc:eBcc: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.
