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

# Registri di audit

> Chi ha fatto cosa in un workspace: membri, permessi, API Key, integrazioni, impostazioni e modifiche ai contenuti, con l'indirizzo di provenienza e se l'azione era consentita. Registro in sola aggiunta, esportabile, con un periodo di conservazione che decidi tu.

## Panoramica

Il registro di audit annota ogni azione del piano di controllo eseguita su un deployment: un membro invitato, un insieme di permessi modificato, una API Key creata, un'integrazione modificata, un template salvato, un broadcast programmato, un contatto eliminato, la licenza installata.

Ogni voce indica l'autore, l'azione, il suo obiettivo, l'indirizzo IP e lo user agent di provenienza, l'id della richiesta e se l'azione è riuscita, è fallita o è stata rifiutata. Le azioni sensibili per la sicurezza riportano anche lo stato prima e dopo la modifica, con ogni segreto oscurato.

Non annota mai il piano dei dati (upsert dei contatti, invii, tracciamento, eventi personalizzati), che può arrivare a migliaia di richieste al minuto e ha il suo posto nei [Log](https://www.notifuse.com/it/docs/features/logs.md).

I registri di audit sono una **funzionalità soggetta a licenza** (Enterprise): la registrazione avviene solo mentre è installata una chiave di licenza che copre `audit_logs`. Leggere, esportare e configurare la conservazione non richiedono mai la licenza, quindi la pagina funziona in qualsiasi stato della licenza su ciò che è stato registrato. Vedi [Chiavi di licenza](https://www.notifuse.com/it/docs/self-hosting/licence.md).

Su Notifuse Cloud la chiave è gestita per te, e i registri di audit vengono registrati nel piano Business. Vedi [Su Notifuse Cloud](https://www.notifuse.com/it/docs/self-hosting/licence.md#on-notifuse-cloud).

> [!NOTE]
>
> **Niente viene rifiutato, niente viene nascosto.** Un deployment senza licenza non scrive alcuna voce e non riceve alcun avviso. Un deployment la cui chiave scade smette di registrare dopo il periodo di tolleranza di 30 giorni e scrive una voce di segnalazione, `licence.recordingStopped`, così l'interruzione resta visibile. Se installi di nuovo una chiave, viene scritto `licence.recordingResumed`.

## Dove trovarlo

**Log → Registro di audit** in un workspace mostra le voci di quel workspace, accanto ai log dei messaggi e dei webhook. Un utente root (un `ROOT_EMAIL`) può passare la stessa scheda a **Intero deployment**: tutti i workspace più le voci a livello di deployment che non appartengono ad alcun workspace (accessi, licenza, impostazioni di sistema).

I proprietari vedono sempre la scheda. Un membro o una API Key la vedono solo se hanno il permesso di lettura **Registri di audit**. Questo permesso va concesso esplicitamente e non fa mai parte dell'"accesso completo", perché l'accesso completo non dovrebbe implicare la lettura dell'indirizzo email, dell'indirizzo IP e delle azioni rifiutate di ogni collega. Un membro che ha solo questo permesso vede la voce di menu Log e soltanto questa scheda.

Ogni voce si legge come una frase, per esempio "Ha invitato **[ann@example.com](mailto:ann@example.com)**", accanto all'autore, alla risorsa e, quando la richiesta non è riuscita, al suo esito. Cliccando una voce la apri in un pannello laterale con l'azione, l'esito e lo stato HTTP, l'autore, l'obiettivo, l'indirizzo IP, lo user agent, l'id della richiesta, lo stato prima e dopo la modifica, i metadati e la voce grezza.

![Scheda del registro di audit nella sezione Log](https://www.notifuse.com/docs/assets/screenshots/audit_logs.png)

![Una voce del registro di audit aperta nel pannello laterale: azione, esito, autore, obiettivo, indirizzo IP, user agent, id della richiesta e metadati](https://www.notifuse.com/docs/assets/screenshots/audit_logs_entry.png)

**Impostazioni → Registro di audit** è dove un proprietario imposta la conservazione del workspace, e dove compare l'avviso sulla licenza quando non viene registrato nulla.

## Cosa contiene una voce

| Campo                                                               | Significato                                                                                                                                                                                                                                |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `occurred_at`                                                       | Quando l'azione è stata completata, in UTC.                                                                                                                                                                                                |
| `action`                                                            | La route RPC che l'ha eseguita, testuale: `workspaces.inviteMember`, `templates.update`, `contacts.delete`.                                                                                                                                |
| `category`                                                          | Un raggruppamento per i filtri: `auth`, `licence`, `system`, `workspaces`, `members`, `api_keys`, `integrations`, `webhooks`, `templates`, `broadcasts`, `automations`, `lists`, `segments`, `transactional`, `blog`, `contacts`, `audit`. |
| `outcome`                                                           | `success`, `failure` (la richiesta è stata rifiutata per un altro motivo, oppure un accesso non è riuscito) o `denied` (403 o 402).                                                                                                        |
| `status_code`                                                       | Lo stato HTTP con cui ha risposto la richiesta.                                                                                                                                                                                            |
| `actor_type`, `actor_id`, `actor_email`, `actor_name`, `actor_role` | Chi l'ha fatto: un `user`, una `api_key`, il `system` (pulizie della conservazione, voci di segnalazione della licenza) o `anonymous` (un accesso non riuscito). Il ruolo è `owner`, `member` o `root`.                                    |
| `auth_method`                                                       | `session`, `api_key`, `magic_code`, `sso` o `root_password`.                                                                                                                                                                               |
| `target_type`, `target_id`, `target_name`                           | Su cosa è stata eseguita l'azione.                                                                                                                                                                                                         |
| `ip_address`, `user_agent`, `request_id`                            | Da dove è arrivata. L'id della richiesta viene restituito in ogni risposta dell'API come `X-Request-ID`, così puoi collegare una voce a una riga del log della tua applicazione.                                                           |
| `changes`                                                           | Stato prima e dopo dei campi modificati, nella forma `{ "field": { "old": …, "new": … } }`. Password, segreti, token e chiavi vengono sostituiti da `[redacted]` su entrambi i lati; resta traccia del fatto che sono cambiati.            |
| `metadata`                                                          | Dettagli liberi: l'ambito del permesso concesso, il numero di contatti importati, il motivo per cui un accesso non è riuscito.                                                                                                             |

## Cosa viene registrato

Ogni route `POST /api/…` qui sotto viene registrata con il proprio nome. Le letture non vengono registrate, con un'eccezione: l'esportazione dei contatti della console chiede la prima pagina di `contacts.list` con `export=true`, e quella richiesta viene registrata come `contacts.export`. Un client API che scorre da sé le pagine dell'elenco fa letture normali, che non vengono registrate.

| Categoria       | Azioni                                                                                                                                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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` restituisce questo catalogo, da cui la console costruisce il filtro per azione.

**Anche i fallimenti vengono registrati.** Un accesso con un indirizzo sconosciuto, un codice errato o scaduto, un tentativo bloccato dal limite di frequenza: la risposta non rivela nulla, e la voce dice il perché (`metadata.reason`). Una richiesta rifiutata da un controllo dei permessi viene registrata come `denied` con la risorsa e il permesso mancanti; una rifiutata dalla licenza è `denied` con la funzionalità che le serviva.

**Non registrati**: il piano dei dati (`contacts.upsert`, `customEvents.upsert`, `transactional.send`, `lists.subscribe` e le altre route per singolo contatto), le letture, i test e le anteprime, gli endpoint interni delle attività, e un broadcast messo in pausa automaticamente dal circuit breaker, perché questo avviene nel percorso di invio, che non contiene alcun controllo di licenza.

## Filtri ed esportazione

La casella di ricerca accetta un indirizzo IP, l'email di un autore o l'id di un obiettivo, e mostra in base a quale dei tre sta cercando. Un indirizzo IP e un id di obiettivo devono corrispondere esattamente; un'email corrisponde anche in parte.

Accanto ci sono i filtri per il periodo (dalle ultime 24 ore agli ultimi 90 giorni, tutto il periodo o un intervallo personalizzato), per l'autore (tu, un membro o una chiave nella vista del workspace; qualsiasi API Key, il sistema o un visitatore non connesso in entrambe le viste) e per la risorsa. **+ Filtro** aggiunge l'azione, l'esito, l'email dell'autore, l'id dell'obiettivo e l'indirizzo IP.

Ogni filtro resta nel link della pagina, così puoi condividere o salvare tra i preferiti una vista filtrata. L'API accetta gli stessi filtri più `target_type`. Le pagine si basano su un cursore, dalla più recente, e nella vista del workspace il fondo dell'elenco indica per quanto tempo il workspace conserva le sue voci.

**Esporta** scarica il filtro corrente in CSV o NDJSON, fino a 100 000 righe. Un'esportazione che raggiunge il limite termina con una riga di segnalazione `export.truncated` che riporta `max_rows`, così un file troncato non passa mai per completo; restringi l'intervallo di date ed esporta di nuovo.

L'esportazione stessa viene registrata come `auditLogs.export`. Ogni voce ha un id, e il pulsante **Copia link** del pannello laterale ti dà un link che apre la pagina su quella voce, anche quando si trova molto in basso nell'elenco.

## Conservazione

Le voci più vecchie del periodo di conservazione vengono eliminate una volta al giorno. Il valore predefinito è **365 giorni**. Un proprietario del workspace può impostare la conservazione propria del workspace in Impostazioni → Registro di audit (0 conserva ogni voce per sempre, altrimenti da 30 a 3650 giorni).

Un utente root imposta il valore predefinito del deployment nelle impostazioni di sistema; questo vale anche per le voci a livello di deployment e per quelle dei workspace che non esistono più. Ogni pulizia che ha rimosso qualcosa viene registrata come `audit.purged`, con il conteggio.

La conservazione funziona in qualsiasi stato della licenza: l'eliminazione dei dati non dipende mai dalla licenza.

## Integrità

La tabella è **in sola aggiunta** (append-only): un trigger del database rifiuta ogni `UPDATE` e `TRUNCATE`, e ogni `DELETE` tranne quelli eseguiti dalla funzione di conservazione. Nessun percorso del codice di Notifuse riscrive lo storico, e nemmeno un'istruzione SQL lanciata per errore con il suo ruolo di database può farlo.

Cosa non impedisce: il proprietario del database, o un superuser, può disattivare il trigger o eliminare la tabella. La garanzia è "l'applicazione non può alterare il registro", non "nessuno può farlo". Se devi dimostrarlo a un revisore, fai un backup della tabella fuori banda, con una frequenza che il revisore accetta.

Le voci sono salvate nel database di sistema, non nel database del workspace, quindi eliminare un workspace non cancella nulla dal registro: resta traccia di chi l'ha eliminato e di cosa aveva fatto prima.

## API

I quattro endpoint sono documentati nel riferimento 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). Una API Key può chiamarli se ha il permesso di lettura Registri di audit, ed è così che un SIEM recupera il registro a intervalli regolari.

La conservazione si imposta via API con [`workspaces.setAuditLogSettings`](https://www.notifuse.com/docs/api-reference/audit-logs/set-the-workspace-audit-log-retention.md), che solo un proprietario del workspace può chiamare: nessun permesso lo consente.
