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

# Logs de auditoria

> Quem fez o quê em um workspace: membros, permissões, chaves API, integrações, configurações e alterações de conteúdo, com o endereço de origem e se a ação foi permitida. Somente acréscimo, exportável, com uma retenção que você controla.

## Visão geral

O log de auditoria registra cada ação do plano de controle feita em um deployment: um membro convidado, um conjunto de permissões alterado, uma chave API criada, uma integração editada, um template salvo, um broadcast agendado, um contato excluído, a licença instalada. Cada entrada indica o autor, a ação, o alvo, o endereço IP e o user agent de origem, o ID da requisição e se ela teve sucesso, falhou ou foi recusada. As ações sensíveis para a segurança também guardam o antes e o depois do que mudou, com todos os segredos ocultados.

Ele nunca registra o plano de dados (upserts de contatos, envios, rastreamento, eventos personalizados), que pode chegar a milhares de requisições por minuto e fica em [Logs](https://www.notifuse.com/pt/docs/features/logs.md).

Os logs de auditoria são uma **capacidade licenciada** (Enterprise): o registro só acontece enquanto houver uma chave de licença instalada que cubra `audit_logs`. Ler, exportar e configurar a retenção nunca dependem da licença, então a página funciona em qualquer estado de licença com o que tiver sido registrado. Veja [Chaves de licença](https://www.notifuse.com/pt/docs/self-hosting/licence.md).

No Notifuse Cloud, a chave é gerenciada para você, e os logs de auditoria são registrados no plano Business. Veja [No Notifuse Cloud](https://www.notifuse.com/pt/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> **Nada é recusado, nada é escondido.** Um deployment sem licença não grava nenhuma entrada e não recebe nenhum aviso. Um deployment cuja chave expira para de registrar depois do período de carência de 30 dias e grava uma entrada de marcação, `licence.recordingStopped`, para que a interrupção nunca passe despercebida. Instalar uma chave de novo grava `licence.recordingResumed`.

## Onde encontrar

**Logs → Log de auditoria**, em um workspace, mostra as entradas desse workspace, ao lado dos logs de mensagens e de webhooks. Um usuário root (um `ROOT_EMAIL`) pode mudar a mesma aba para **Todo o deployment**: todos os workspaces, mais as entradas do nível do deployment que não pertencem a nenhum workspace (logins, a licença, as configurações do sistema).

Os proprietários sempre veem a aba. Um membro ou uma chave API só a vê quando recebe a permissão de leitura **Logs de auditoria**. Essa permissão precisa ser concedida de forma explícita e nunca faz parte do "acesso total", porque o acesso total não deveria incluir ler o endereço de email, o endereço IP e as ações recusadas de cada colega. Um membro que só tem essa permissão vê o item Logs no menu e apenas esta aba.

Cada entrada é lida como uma frase, por exemplo "Convidou **[ann@example.com](mailto:ann@example.com)**", ao lado do autor, do recurso e, quando a requisição não teve sucesso, do resultado. Clicar em uma entrada abre um painel lateral com a ação, o resultado e o status HTTP, o autor, o alvo, o endereço IP, o user agent, o ID da requisição, o antes e o depois do que mudou, os metadados e a entrada bruta.

![Aba Log de auditoria na seção Logs](https://www.notifuse.com/docs/assets/screenshots/audit_logs.png)

![Uma entrada do log de auditoria aberta no painel lateral: ação, resultado, autor, alvo, endereço IP, user agent, ID da requisição e metadados](https://www.notifuse.com/docs/assets/screenshots/audit_logs_entry.png)

**Configurações → Log de auditoria** é onde um proprietário define a retenção do workspace e onde aparece o aviso de licença quando nada está sendo registrado.

## O que uma entrada contém

| Campo                                                               | Significado                                                                                                                                                                                                                             |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `occurred_at`                                                       | Quando a ação terminou, em UTC.                                                                                                                                                                                                         |
| `action`                                                            | A rota RPC que a executou, tal como é: `workspaces.inviteMember`, `templates.update`, `contacts.delete`.                                                                                                                                |
| `category`                                                          | Um agrupamento para filtrar: `auth`, `licence`, `system`, `workspaces`, `members`, `api_keys`, `integrations`, `webhooks`, `templates`, `broadcasts`, `automations`, `lists`, `segments`, `transactional`, `blog`, `contacts`, `audit`. |
| `outcome`                                                           | `success`, `failure` (a requisição foi recusada por outro motivo, ou um login falhou) ou `denied` (403 ou 402).                                                                                                                         |
| `status_code`                                                       | O status HTTP com que a requisição respondeu.                                                                                                                                                                                           |
| `actor_type`, `actor_id`, `actor_email`, `actor_name`, `actor_role` | Quem fez: um `user`, uma `api_key`, o `system` (limpezas da retenção, marcações de licença) ou `anonymous` (um login que falhou). O papel é `owner`, `member` ou `root`.                                                                |
| `auth_method`                                                       | `session`, `api_key`, `magic_code`, `sso` ou `root_password`.                                                                                                                                                                           |
| `target_type`, `target_id`, `target_name`                           | Sobre o que a ação foi feita.                                                                                                                                                                                                           |
| `ip_address`, `user_agent`, `request_id`                            | De onde veio. O ID da requisição volta em toda resposta da API como `X-Request-ID`, então uma entrada pode ser ligada a uma linha do log da sua aplicação.                                                                              |
| `changes`                                                           | O antes e o depois dos campos que mudaram, no formato `{ "field": { "old": …, "new": … } }`. Senhas, segredos, tokens e chaves são substituídos por `[redacted]` dos dois lados; o fato de terem mudado fica registrado.                |
| `metadata`                                                          | Detalhes livres: o escopo de permissão concedido, o número de contatos importados, o motivo da falha de um login.                                                                                                                       |

## O que é registrado

Cada rota `POST /api/…` abaixo é registrada com o próprio nome. As leituras não são registradas, com uma exceção: a exportação de contatos do console pede a primeira página de `contacts.list` com `export=true`, e essa requisição é registrada como `contacts.export`. Um cliente da API que percorre a lista por conta própria faz leituras comuns, que não são registradas.

| Categoria       | Ações                                                                                                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| auth            | `user.signin`, `user.verify`, `user.rootSignin`, `user.oidc.exchange`, `user.oidc.callback`, `user.logout`, `setup.initialize`                                                                         |
| licence         | `licence.set`, `licence.recordingStopped`, `licence.recordingResumed`                                                                                                                                  |
| system          | `settings.update`                                                                                                                                                                                      |
| workspaces      | `workspaces.create`, `workspaces.update`, `workspaces.delete`, `workspaces.setBlogSettings`, `workspaces.setCustomFieldLabels`, `workspaces.setWebAnalyticsSettings`, `workspaces.setAuditLogSettings` |
| members         | `workspaces.inviteMember`, `workspaces.acceptInvitation`, `workspaces.joinInvitation`, `workspaces.deleteInvitation`, `workspaces.removeMember`, `workspaces.setUserPermissions`                       |
| api_keys        | `workspaces.createAPIKey`, `workspaces.connectZapier`                                                                                                                                                  |
| integrations    | `workspaces.createIntegration`, `workspaces.updateIntegration`, `workspaces.deleteIntegration`, `ses.enableTenantIsolation`, `webhooks.register`                                                       |
| webhooks        | `webhookSubscriptions.create`, `.update`, `.delete`, `.toggle`, `.regenerateSecret`                                                                                                                    |
| templates       | `templates.create`, `.update`, `.delete`, `templateBlocks.create`, `.update`, `.delete`                                                                                                                |
| broadcasts      | `broadcasts.create`, `.update`, `.schedule`, `.pause`, `.resume`, `.cancel`, `.delete`, `.retryFailed`, `.selectWinner`, `.sendToIndividual`                                                           |
| automations     | `automations.create`, `.update`, `.delete`, `.activate`, `.pause`                                                                                                                                      |
| lists, segments | `lists.create`, `.update`, `.delete`, `segments.create`, `.update`, `.delete`, `.rebuild`                                                                                                              |
| transactional   | `transactional.create`, `.update`, `.delete`                                                                                                                                                           |
| blog            | `blogPosts.*`, `blogCategories.*`, `blogThemes.*`                                                                                                                                                      |
| contacts        | `contacts.delete`, `contacts.import`, `contacts.export`, `customEvents.import`, `annotations.*`, `webAnalytics.backfillStart`, `.backfillCancel`                                                       |
| audit           | `auditLogs.export`, `audit.purged`                                                                                                                                                                     |

`GET /api/auditLogs.actions` retorna este catálogo, que é a base do filtro de ações do console.

**As falhas também são registradas.** Um login com um endereço desconhecido, um código errado ou expirado, uma tentativa barrada pelo limite de requisições: a resposta não revela nada, e a entrada diz o motivo (`metadata.reason`). Uma requisição recusada por uma verificação de permissão é registrada como `denied`, com o recurso e a permissão que faltavam; uma recusada pela licença é `denied`, com a funcionalidade que ela exigia.

**Não são registrados**: o plano de dados (`contacts.upsert`, `customEvents.upsert`, `transactional.send`, `lists.subscribe` e as outras rotas por contato), as leituras, os testes e as visualizações, os endpoints internos de tarefas e um broadcast pausado automaticamente pelo circuit breaker, porque isso roda no caminho de envio, que não tem nenhuma verificação de licença.

## Filtros e exportação

A caixa de busca aceita um endereço IP, o email de um autor ou o ID de um alvo, e mostra por qual deles está buscando. Um endereço IP e um ID de alvo precisam corresponder exatamente; um email corresponde a qualquer parte dele.

Ao lado ficam os filtros de período (das últimas 24 horas aos últimos 90 dias, todo o período ou um intervalo personalizado), de autor (você mesmo, um membro ou uma chave na visão do workspace; qualquer chave API, o sistema ou um visitante sem login nas duas visões) e de recurso. **+ Filtro** acrescenta a ação, o resultado, o email do autor, o ID do alvo e o endereço IP.

Todos os filtros ficam no link da página, então você pode compartilhar ou salvar nos favoritos uma visão filtrada. A API aceita os mesmos filtros, mais `target_type`. As páginas usam cursor, das mais recentes para as mais antigas, e na visão do workspace o rodapé da lista mostra por quanto tempo o workspace guarda as entradas.

**Exportar** baixa o filtro atual em CSV ou NDJSON, até 100 000 linhas. Uma exportação que atinge o limite termina com uma linha de marcação `export.truncated` que traz `max_rows`, para que um arquivo cortado nunca passe por completo; reduza o intervalo de datas e exporte de novo.

A própria exportação é registrada como `auditLogs.export`. Toda entrada tem um ID, e o botão **Copiar link** do painel lateral gera um link que abre a página nessa entrada, mesmo quando ela está bem abaixo na lista.

## Retenção

As entradas mais antigas que a retenção são excluídas uma vez por dia. O padrão é **365 dias**. O proprietário de um workspace pode definir a retenção do próprio workspace em Configurações → Log de auditoria (0 guarda todas as entradas para sempre; caso contrário, de 30 a 3650 dias).

Um usuário root define o padrão do deployment nas configurações do sistema. Esse padrão também vale para as entradas do nível do deployment e para as entradas de workspaces que não existem mais. Cada limpeza que removeu algo é registrada como `audit.purged`, com a contagem.

A retenção roda em qualquer estado de licença: excluir dados nunca depende da licença.

## Integridade

A tabela é **somente de acréscimo**: um trigger do banco de dados recusa todo `UPDATE` e `TRUNCATE`, e todo `DELETE` que não venha da função de retenção. Nenhum caminho de código do Notifuse reescreve o histórico, e uma instrução SQL avulsa executada pelo papel de banco de dados dele também não consegue.

O que isso não impede: o dono do banco de dados, ou um superusuário, pode desativar o trigger ou apagar a tabela. A garantia é "a aplicação não consegue alterar o log", e não "ninguém consegue". Se você precisa provar isso a um auditor, faça backup da tabela por fora, com uma frequência que ele aceite.

As entradas ficam no banco de dados do sistema, e não no banco de dados do workspace. Por isso, excluir um workspace não apaga nada do log: o registro de quem o excluiu, e do que essa pessoa fez antes, continua lá.

## API

Os quatro endpoints estão documentados na referência da API: [`auditLogs.list`](https://www.notifuse.com/docs/api-reference/audit-logs/list-audit-logs.md), [`auditLogs.get`](https://www.notifuse.com/docs/api-reference/audit-logs/get-an-audit-log-entry.md), [`auditLogs.actions`](https://www.notifuse.com/docs/api-reference/audit-logs/list-audit-actions.md) e [`auditLogs.export`](https://www.notifuse.com/docs/api-reference/audit-logs/export-audit-logs.md). Uma chave API pode chamá-los quando recebe a permissão de leitura Logs de auditoria; é assim que um SIEM busca o log em intervalos regulares.

A retenção é definida pela API com [`workspaces.setAuditLogSettings`](https://www.notifuse.com/docs/api-reference/audit-logs/set-the-workspace-audit-log-retention.md), que só o proprietário do workspace pode chamar: nenhuma permissão dá esse acesso.
