Elenca i log

GET /v1/logs · autorizzazione logs:read

Elenca i record di log dell'ambiente (accessi, sessioni, token, MFA, protezione dagli attacchi e altro) con paginazione a cursore, dal più recente. I record più vecchi della finestra di conservazione del tuo piano (Free 7, Startup 14, Business 30, Enterprise 90 giorni) non vengono mai restituiti.

Richiesta

Parametro	In	Obbligatorio	Descrizione
`limit`	query	no	Dimensione della pagina, da 1 a 100. Predefinito 20.
`after`	query	no	Cursore opaco da `list_metadata.after` (record più vecchi). Esclusivo con `before`.
`before`	query	no	Cursore opaco da `list_metadata.before` (record più recenti). Esclusivo con `after`.
`from`	query	no	Orario RFC 3339; record a partire da questo orario o successivi. Deve rientrare nella finestra di conservazione.
`to`	query	no	Orario RFC 3339; record precedenti a questo orario. Deve essere successivo a `from`.
`type`	query	no	Prefisso del tipo di log, come `authentication.` o `session.created`. Ripeti il parametro per fino a 20 valori; viene restituito un record che corrisponde a uno qualsiasi di essi.
`outcome`	query	no	`success`, `failure`, `denied` o `error`.
`user_id`, `org_id`, `application_id`, `connection_id`, `directory_id`, `session_id`	query	no	Corrispondenza esatta sull'id con prefisso (`usr_`, `org_`, `app_`, `conn_`, `dir_`, `ses_`).
`request_id`	query	no	`Idp-Request-Id` di una richiesta (UUID), per esempio l'id mostrato in una pagina di errore di accesso ospitata.
`correlation_id`	query	no	`Idp-Correlation-Id` di un flusso di lavoro (UUID).
`ip`	query	no	Indirizzo IP o blocco CIDR (`203.0.113.0/24`). Richiede `audit-events:read_ip`.
`ip_country`	query	no	Paese dell'IP, codice ISO 3166-1 alpha-2 in maiuscolo (`DE`).
`q`	query	no	Prefisso dell'indicazione mascherata dell'identificatore (`j***@`). Richiede `users:read_pii`.

I record sono sempre ordinati per occurred_at, dal più recente; non esiste il parametro order (order=desc è accettato, qualsiasi altro valore fallisce con validation_failed). Un cursore è valido solo con i filtri per cui è stato emesso.

I filtri ip e q richiedono la rispettiva autorizzazione anche se servono solo a restringere il risultato: senza di essa la richiesta fallisce con 403 insufficient_permissions prima di qualsiasi ricerca, così una chiave non può sondare valori che non è autorizzata a leggere.

Risposta

200 OK. data contiene i record della pagina; list_metadata.after punta ai record più vecchi e list_metadata.before a quelli più recenti (null quando non ce ne sono). Non viene restituito alcun conteggio totale. I campi vuoti sono null.

ip, ip_asn, user_agent e user_agent_family sono presenti solo quando la chiave ha l'autorizzazione audit-events:read_ip, e identifier_hint solo quando ha users:read_pii. Senza l'autorizzazione il campo viene omesso del tutto (nessun valore mascherato). ip_country viene sempre restituito.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "type": "authentication.password.failed",
      "outcome": "failure",
      "reason_code": "invalid_credentials",
      "user_id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
      "org_id": null,
      "application_id": "app_01j9xk3m7q8r2s4t6v8w0y2z4b",
      "connection_id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4c",
      "directory_id": null,
      "session_id": null,
      "identifier_hint": "a***@e***.com",
      "ip": "203.0.113.7",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent": "Mozilla/5.0 (X11; Linux x86_64)",
      "user_agent_family": "Firefox",
      "risk": null,
      "auth_context": null,
      "act_chain": null,
      "details": {"attempt": 3},
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}

Errori

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

HTTP	`code`	Quando
400	`invalid_cursor`	Il cursore è malformato o non è stato emesso per questa richiesta.
400	`invalid_filter`	Il servizio di log ha rifiutato un filtro o il cursore.
400	`range_outside_retention`	`from` è precedente alla finestra di conservazione del tuo piano.
422	`validation_failed`	Un parametro di query non è valido (`limit` fuori intervallo, timestamp errato, `to` non successivo a `from`, più di 20 valori `type`, id o IP malformato, parametro ripetuto).
401	`unauthenticated`	La chiave API manca, non è valida o è stata revocata.
403	`insufficient_permissions`	La chiave non ha `logs:read`, oppure usa `ip` senza `audit-events:read_ip` o `q` senza `users:read_pii` (`required_permissions` elenca ciò che la richiesta necessita).
429	`rate_limited`	È stato superato il rate limit; rispetta `Retry-After`.
503	`service_unavailable`	Una dipendenza non è temporaneamente disponibile; riprova più tardi.

Esempio

curl "https://api.eu.keenauth.com/v1/logs?type=authentication.&outcome=failure&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Dati personali

Questo endpoint contiene dati personali: log dell'ambiente. 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.