API Reference / Audit log

Audit log

L'audit log è il registro append-only delle azioni rilevanti sull'istanza: chi ha fatto cosa, su quale oggetto, quando e con che esito. Due endpoint di sola lettura: l'elenco filtrabile delle voci e le facet per popolare i filtri.

Solo amministratori

Entrambi gli endpoint richiedono un token di un amministratore: un utente autenticato ma non admin riceve 403 FORBIDDEN. La pagina web corrispondente nel CRM è /admin/audit-logs (che non è un path API).

01La voce di audit

Ogni voce restituita dall'API ha questa forma. Le date sono stringhe ISO 8601 in UTC; i campi non valorizzati per quel tipo di evento sono null.

Attributo	Tipo	Descrizione
id	integer	Identificativo univoco della voce.
actor_user_id	integer \| null	Utente che ha compiuto l'azione (`null` per eventi anonimi, es. login fallito).
actor_username	string \| null	Username dell'attore, risolto dall'API per comodità.
event_type	string	Tipo di evento (es. `auth_login`, `user_updated`).
module	string \| null	Area applicativa (es. `auth`, `users`, `workflows`).
action	string \| null	Azione compiuta (es. `create`, `update`, `login`).
scope	string \| null	Scope con cui l'azione è stata eseguita, quando rilevante.
target_type	string \| null	Tipo dell'oggetto toccato (es. `user`, `workflow`).
target_id	string \| null	Identificativo dell'oggetto (stringa: può essere un id o `*`).
status	string	Esito: `success`, `failed`, `denied`.
request_id	string \| null	Id della richiesta HTTP: correla la voce con i log applicativi.
correlation_id	string \| null	Id di correlazione tra voci della stessa operazione composita.
ip_address	string \| null	IP del client (affidabile dietro proxy configurato).
user_agent	string \| null	User agent del client.
details	object \| null	Contesto specifico dell'evento (JSON libero, dipende dal tipo).
created_at	string	Data/ora dell'evento (ISO 8601).

json · una voce di audit

{
  "id": 5182,
  "actor_user_id": 7,
  "actor_username": "mrossi",
  "event_type": "user_updated",
  "module": "users",
  "action": "update",
  "scope": null,
  "target_type": "user",
  "target_id": "42",
  "status": "success",
  "request_id": "5f0e8a2c-1b7d-4c40-9a3e-7f21d6b90c11",
  "correlation_id": null,
  "ip_address": "203.0.113.10",
  "user_agent": "Mozilla/5.0 …",
  "details": null,
  "created_at": "2026-07-16T09:41:00.000Z"
}

02Endpoint

Metodo	Path	Accesso	Cosa fa
GET	/api/audit-logs	admin	Elenco paginato e filtrabile delle voci.
GET	/api/audit-logs/facets	admin	Valori distinti (con conteggi) per popolare i filtri.

03Elencare le voci di audit

GET /api/audit-logs admin

Restituisce le voci di audit più recenti, paginate e ordinabili. Tutti i filtri sono parametri query e si compongono in AND.

Parametri query: paginazione e ordinamento

Parametro	Tipo		Descrizione
limit	integer	opzionale	Righe per pagina. Default 50, max 200.
offset	integer	opzionale	Righe da saltare (default 0).
sort_by	string	opzionale	Uno tra `id`, `created_at`, `event_type`, `module`, `action`, `status`, `actor_user_id`. Default `created_at`.
sort_dir	string	opzionale	`asc` o `desc` (default `desc`).

Parametri query: filtri

Parametro	Tipo	Corrispondenza	Descrizione
q	string	parziale	Ricerca libera (case-insensitive) su tipo evento, modulo, azione, target, request id e correlation id. Max 255 caratteri.
event_type	string	esatta	Tipo di evento (es. `auth_login`). Max 80.
module	string	esatta	Area applicativa (es. `users`). Max 80.
action	string	esatta	Azione (es. `update`). Max 80.
status	string	esatta	Esito (`success`, `failed`, `denied`). Max 40.
target_type	string	esatta	Tipo dell'oggetto toccato. Max 80.
target_id	string	parziale	Identificativo (o parte) dell'oggetto. Max 120.
request_id	string	parziale	Id (o parte) della richiesta HTTP. Max 120.
correlation_id	string	parziale	Id (o parte) di correlazione. Max 120.
actor_user_id	integer	esatta	Id dell'utente attore.
created_from	string (data)	YYYY-MM-DD	Dal giorno indicato incluso (dalla mezzanotte).
created_to	string (data)	YYYY-MM-DD	Fino al giorno indicato incluso (fine giornata).

Richiesta

curl "https://crm.tuodominio.it/api/audit-logs?module=users&status=success&created_from=2026-07-01&limit=2" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/audit-logs?module=users&status=success&created_from=2026-07-01&limit=2", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{
  "success": true,
  "data": {
    "items": [ { "id": 5182, "event_type": "user_updated", … }, { "id": 5179, … } ],
    "pagination": { "limit": 2, "offset": 0, "count": 2, "totalCount": 87, "sortBy": "created_at", "sortDir": "desc" }
  }
}

Nota: totalCount

A differenza delle liste dei moduli (dove count conta solo le righe della pagina), qui la paginazione include anche totalCount: il totale delle voci che soddisfano i filtri, utile per una paginazione numerata.

Esiti

Stato	Codice	Quando
200	·	Elenco restituito.
401	`UNAUTHORIZED`	Token assente, scaduto o non valido.
403	`FORBIDDEN`	Utente autenticato ma non amministratore.
422	`VALIDATION_ERROR`	Parametro fuori dai limiti: `sort_by` non ammesso, data non in formato YYYY-MM-DD, filtro oltre la lunghezza massima.

Anche la consultazione è tracciata

Ogni lettura dell'elenco genera a sua volta una voce audit_logs_viewed con i filtri usati e quante righe sono state restituite: chi consulta l'audit log lascia traccia nell'audit log.

GET /api/audit-logs/facets admin

Restituisce i valori distinti presenti nel registro per le cinque dimensioni filtrabili, con il conteggio delle voci: è pensato per popolare le tendine dei filtri. Ogni lista è ordinata per frequenza decrescente (max 120 valori).

Parametri

Nessuno: serve solo l'header Authorization: Bearer <accessToken> di un amministratore.

Richiesta

curl "https://crm.tuodominio.it/api/audit-logs/facets" \
  -H "Authorization: Bearer <accessToken>"

const res = await fetch("https://crm.tuodominio.it/api/audit-logs/facets", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { data } = await res.json();

Risposta · 200

json

{
  "success": true,
  "data": {
    "eventTypes": [ { "value": "auth_login", "count": 312 }, { "value": "user_updated", "count": 54 }, … ],
    "modules": [ { "value": "auth", "count": 340 }, … ],
    "actions": [ { "value": "login", "count": 312 }, … ],
    "statuses": [ { "value": "success", "count": 690 }, { "value": "failed", "count": 12 } ],
    "targetTypes": [ { "value": "user", "count": 61 }, … ]
  }
}

Esiti

Stato	Codice	Quando
200	·	Facet restituite.
401	`UNAUTHORIZED`	Token assente, scaduto o non valido.
403	`FORBIDDEN`	Utente autenticato ma non amministratore.

← PrecedenteOps e health Successiva →·

Audit log

01La voce di audit

02Endpoint

03Elencare le voci di audit

04Facet per i filtri