Panoramica API AuditRails: endpoint e convenzioni

L’API di AuditRails è un’interfaccia REST che consente di ingerire eventi di audit a prova di manomissione, recuperare e filtrare la cronologia dei log, verificare l’integrità crittografica della catena e sfogliare il catalogo delle azioni di conformità. Tutte le richieste vengono effettuate via HTTPS all’URL di base https://api.auditrails.io, e ogni endpoint è versionato sotto /v1/. I corpi di richiesta e risposta usano application/json.

I flussi DSAR (Data Subject Access Request, richiesta dell’interessato) sono disponibili esclusivamente tramite la dashboard di AuditRails e non sono esposti tramite l’API con token bearer.

URL di base

https://api.auditrails.io/v1

Convenzioni di richiesta e risposta

Ogni richiesta deve includere l’header Content-Type: application/json insieme al tuo header Authorization. Ogni risposta — inclusi gli errori — contiene un header X-Request-Id nel formato req_<ULID>. Conserva questo valore quando contatti il supporto; identifica in modo univoco l’esatta transazione lato server.

Formato degli errori

Quando una richiesta fallisce, AuditRails restituisce un corpo di errore strutturato così da sapere sempre cosa è andato storto e dove approfondire.

{
  "error": {
    "code": "validation/missing_action",
    "message": "The 'action' field is required.",
    "request_id": "req_01HX7YGBFZ3QK8N9VMJT5RPCE4",
    "doc_url": "https://docs.auditrails.io/reference/error-codes"
  }
}

Campo	Tipo	Descrizione
`code`	string	Codice di errore leggibile da macchina in formato `categoria/slug`.
`message`	string	Spiegazione dell’errore leggibile da un umano.
`request_id`	string	Lo stesso ID presente nell’header di risposta `X-Request-Id`.
`doc_url`	string	Link diretto alla pagina di documentazione del codice di errore.

Catalogo degli endpoint

La tabella seguente elenca ogni endpoint disponibile raggruppato per categoria funzionale. Clicca sul nome di un endpoint per saltare alla relativa pagina di riferimento.

Ingestione

Metodo	Percorso	Descrizione
`POST`	`/v1/events`	Ingerisce un singolo evento di audit nel tuo log.
`POST`	`/v1/events/batch`	Ingerisce un lotto fino a 100 eventi di audit in un’unica richiesta.

Lettura e interrogazione

Metodo	Percorso	Descrizione
`GET`	`/v1/events`	Elenca gli eventi di audit con filtri opzionali (attore, azione, intervallo di date e altro).
`GET`	`/v1/events/{log_id}`	Recupera un singolo evento di audit tramite il suo log ID univoco.
`GET`	`/v1/events/verify`	Verifica l’integrità crittografica della tua catena di audit.

Conformità

Metodo	Percorso	Descrizione
`GET`	`/v1/actions`	Recupera il catalogo completo delle azioni di conformità (slug di azione standardizzati).

Esempio rapido

Lo snippet seguente ingerisce il tuo primo evento con un unico comando curl. Sostituisci at_live_xxx con la tua chiave API di produzione.

curl -X POST https://api.auditrails.io/v1/events \
  -H "Authorization: Bearer at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user.login",
    "actor_id": "user_123"
  }'

Autenticazione

Scopri come funzionano le chiavi API, la differenza tra chiavi live e di test, e come gestire gli errori di autenticazione.

Limiti di frequenza

Comprendi i limiti per IP, per piano e per chiave di test, e come gestire con eleganza le risposte 429.

Codici di errore

Sfoglia l’elenco completo dei codici di errore leggibili da macchina restituiti dall’API.

SDK

Usa un SDK ufficiale AuditRails per ottenere retry automatici, risposte tipizzate e altro.

Panoramica

Ingestione

Lettura e verifica

Richieste dell'interessato

Panoramica API AuditRails: endpoint e convenzioni

URL di base

Convenzioni di richiesta e risposta

Formato degli errori

Catalogo degli endpoint

Ingestione

Lettura e interrogazione

Conformità

Esempio rapido

Autenticazione

Limiti di frequenza

Codici di errore

SDK

​URL di base

​Convenzioni di richiesta e risposta

​Formato degli errori

​Catalogo degli endpoint

​Ingestione

​Lettura e interrogazione

​Conformità

​Esempio rapido

Autenticazione

Limiti di frequenza

Codici di errore

SDK

URL di base

Convenzioni di richiesta e risposta

Formato degli errori

Catalogo degli endpoint

Ingestione

Lettura e interrogazione

Conformità

Esempio rapido