Scarica un export di audit

GET /v1/audit-exports/{export_id}/download · autorizzazione audit-exports:read

Fornisce un link monouso al pacchetto di un job di export completato. Le chiavi API (segrete o con restrizioni) e gli utenti della dashboard possono scaricare; per uno scaricamento dalla dashboard serve un accesso recente (step-up, non più vecchio di 5 minuti). Ogni chiamata scrive un record audit_export.downloaded nello stream admin prima che il link venga emesso.

Richiesta

Parametro	In	Obbligatorio	Descrizione
`export_id`	path	sì	ID del job di export, con prefisso `aex_`.

Un job creato con include_ip: true richiede anche audit-events:read_ip sulla chiave che scarica.

Risposta

La risposta dipende dall'header Accept. Entrambe le forme contengono Cache-Control: no-store, Referrer-Policy: no-referrer e Vary: Accept, e scrivono entrambe lo stesso record audit_export.downloaded.

Accept elenca application/json (esplicitamente, con un q diverso da zero; */* non conta): 200 OK con un body JSON. Usa questa forma da un browser o da qualsiasi client che non può leggere un redirect cross-origin: leggi url, poi aprilo.

Campo	Tipo	Descrizione
`url`	string	Link relativo sullo stesso host, `/downloads/audit-exports/{environment_id}/{export_id}/{token}`.
`expires_at`	string (date-time)	Quando il link smette di funzionare (15 minuti dopo l'emissione).

Qualsiasi altro Accept: 302 Found con body vuoto. Location è lo stesso link relativo.
Il link è valido per 15 minuti e funziona una sola volta: il token viene consumato alla prima richiesta, anche se il trasferimento viene interrotto. Chiama di nuovo questa operazione per ottenere un nuovo link.
Il link non richiede credenziali; il token è l'unica credenziale. Mantieni Location (o url) segreto e non registrarlo nei log.
Il file è cifrato a riposo con la chiave dell'ambiente, quindi non viene usato alcun URL presigned dello storage; KeenAuth lo decifra e lo trasmette.

Seguendo il link si ottiene 200 OK con Content-Type: application/x-tar, Content-Length e Content-Disposition: attachment; filename="audit-export-aex_….tar". Il pacchetto tar contiene:

File	Contenuto
`records.ndjson.gz`	Ogni record della catena di ogni ora coperta, in ordine di sequenza, un oggetto JSON per riga: i record corrispondenti in forma completa, gli altri come segnaposto senza contenuto (`"omitted": true`) così la hash chain può essere ricostruita senza rivelarli.
`manifest.json`	Filtro, conteggi, hash del file e, per ogni ora coperta, il checkpoint firmato e la prova di inclusione; JSON canonico (RFC 8785).
`manifest.jws`	Firma ES256 su `manifest.json`; verificala con le chiavi pubbliche in `audit-jwks.json`.

Se la connessione termina prima che arrivino tutti i Content-Length byte, il pacchetto è incompleto; scartalo e richiedi un nuovo link. Un link non valido, già usato o scaduto restituisce 404 not_found.

Errori

Ogni errore è un body application/problem+json con un code stabile.

HTTP	`code`	Quando
401	`unauthenticated`	La chiave API manca, non è valida o è stata revocata.
403	`insufficient_permissions`	La chiave non ha `audit-exports:read`, il job è stato creato con `include_ip` e la chiave non ha `audit-events:read_ip` (`required_permissions` elenca entrambi), oppure il chiamante non è né una chiave API né un utente della dashboard.
404	`not_found`	Il job non esiste, appartiene a un altro ambiente, o l'ID è malformato. Sul link: il token non è valido, è già stato usato o è scaduto.
409	`conflict`	Il job non è ancora completato, oppure il suo file è scaduto.
429	`rate_limited`	È stato superato il rate limit; rispetta `Retry-After`.
503	`service_unavailable`	Una dipendenza è temporaneamente non disponibile; riprova più tardi.

Esempio

curl -L -o audit-export.tar \
  https://api.eu.keenauth.com/v1/audit-exports/aex_01j9xk3m7q8r2s4t6v8w0y2z4e/download \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Con Accept: application/json il link viene restituito come JSON invece che come redirect:

curl https://api.eu.keenauth.com/v1/audit-exports/aex_01j9xk3m7q8r2s4t6v8w0y2z4e/download \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Accept: application/json"

Gli SDK usano la forma JSON e restituiscono url e expires_at. La CLI legge il link da sola, scrive il pacchetto in un file (mai sullo standard output), rifiuta di sovrascrivere un file esistente e stampa la dimensione e l'SHA-256 di ciò che ha scritto:

keenauth audit-exports download aex_01j9xk3m7q8r2s4t6v8w0y2z4e --file audit-export.tar

Dati personali

Questo endpoint contiene dati personali: eventi di audit. Dati personali nelle API di KeenAuth descrive cosa viene memorizzato, per quanto tempo viene conservato e come viene cancellato. Non inviare categorie particolari di dati personali (salute, dati biometrici, religione, opinioni politiche, orientamento sessuale) in nessun campo.