Crea un'esportazione di audit

POST /v1/audit-exports · autorizzazione audit-exports:write

Accoda un job che scrive i record di audit corrispondenti in un pacchetto firmato che puoi verificare senza fidarti di KeenAuth. Il job viene restituito con 202 Accepted; seguilo con Ottieni un'esportazione di audit e scarica il file con Scarica un'esportazione di audit.

Solo le chiavi API (segrete o con restrizioni) possono creare esportazioni; il job registra la chiave come requested_by. L'ambiente viene ricavato dalla chiave.

Richiesta

Idempotency-Key è obbligatoria (da 16 a 64 caratteri, A-Z a-z 0-9 _ -). La stessa chiave con lo stesso corpo restituisce il primo job con Idempotent-Replayed: true; la stessa chiave con un corpo diverso fallisce con 422 idempotency_key_reuse. Gli SDK e la CLI impostano l'intestazione per te.

I filtri sono gli stessi di Elenca gli eventi di audit; un campo omesso non filtra. Differenze:

Campo Tipo Descrizione
stream string admin (predefinito) oppure application.
from RFC 3339 Limite inferiore incluso. Il valore predefinito è l'inizio della finestra di conservazione. Non c'è un limite di 92 giorni; un pacchetto contiene al massimo 50 milioni di righe (segnaposto inclusi).
to RFC 3339 Limite superiore escluso. Il valore predefinito è l'ora attuale; non può essere nel futuro.
action, category, actor_type, actor_id, target_type, target_id, org_id, outcome, request_id, correlation_id, agent_only Come nei filtri dell'elenco. Il filtro client dell'elenco non è disponibile qui; un campo client fallisce con 400 unknown_field.
include_ip boolean Aggiunge indirizzo IP completo e agente utente ai record più recenti di 13 mesi. Richiede anche audit-events:read_ip. Predefinito false. 
{
  "stream": "admin",
  "from": "2026-07-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "action": "user."
}

Al massimo 3 job girano contemporaneamente per ambiente (1 negli ambienti di sviluppo e staging).

Risposta

202 Accepted e il job con status queued. filter mostra il filtro applicato con i valori predefiniti di from e to compilati. recorded_before è il limite dello snapshot: entrano nel pacchetto solo i record memorizzati prima di questo valore.

{
  "id": "aex_01j9xk3m7q8r2s4t6v8w0y2z4e",
  "status": "queued",
  "filter": {
    "stream": "admin",
    "from": "2026-07-01T00:00:00Z",
    "to": "2026-10-01T00:00:00Z",
    "action": "user.",
    "category": null,
    "actor_type": null,
    "actor_id": null,
    "target_type": null,
    "target_id": null,
    "org_id": null,
    "outcome": null,
    "request_id": null,
    "correlation_id": null,
    "agent_only": false
  },
  "include_ip": false,
  "record_count": null,
  "file": null,
  "manifest_sha256": null,
  "failure_reason": null,
  "created_at": "2026-10-19T09:00:00Z",
  "started_at": null,
  "completed_at": null,
  "expires_at": null,
  "recorded_before": "2026-10-19T09:00:00Z",
  "requested_by": {"type": "api_key", "id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d"}
}

Errori

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

HTTP code Quando
400 malformed_request Idempotency-Key manca o è malformata, oppure il corpo non è JSON valido.
400 unknown_field Il corpo contiene un campo non elencato sopra.
400 invalid_filter Il servizio di audit ha rifiutato il filtro, per esempio to nel futuro.
400 range_outside_retention from o to sono fuori dalla finestra di conservazione dell'audit del tuo piano.
422 validation_failed Un campo non è valido (tipo errato, timestamp non valido, to non successivo a from, valore enum sconosciuto, id malformato, stringa vuota).
422 idempotency_key_reuse Idempotency-Key è stata usata con un corpo diverso.
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha audit-exports:write, usa include_ip senza audit-events:read_ip (required_permissions elenca entrambe), oppure il chiamante non è una chiave API.
429 rate_limited Troppi job sono in esecuzione in questo ambiente, oppure è stato superato il limite di frequenza; rispetta Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova più tardi.

Esempio

curl https://api.eu.keenauth.com/v1/audit-exports \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"from": "2026-07-01T00:00:00Z", "to": "2026-10-01T00:00:00Z", "action": "user."}'

keenauth audit-exports create --from 2026-07-01T00:00:00Z --to 2026-10-01T00:00:00Z --action user.

Dati personali

Questo endpoint contiene dati personali: eventi di audit. I 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.