Elenco dei log di un utente

GET /v1/users/{user_id}/logs · autorizzazione logs:read

Elenca i record di log di un utente con paginazione a cursore, dal più recente. Sono i dati alla base della vista di attività utente della dashboard. Segue le stesse regole di Elenco dei log ma accetta solo i filtri from, to, type e org_id; gli altri filtri vengono ignorati.

Ambito dell'organizzazione

Passa org_id per creare una vista diagnostica dei membri per un amministratore dell'organizzazione. La chiave deve avere anche l'autorizzazione organizations:read. Se l'utente non è membro di quell'organizzazione (nessuna appartenenza invited, active o suspended), la richiesta fallisce con 404 not_found, la stessa risposta di un utente sconosciuto. Se l'utente è membro, vengono restituiti solo i record avvenuti nel contesto di quell'organizzazione: quelli il cui org_id è quell'organizzazione. Gli accessi dell'utente al di fuori dell'organizzazione, o nel contesto di un'altra organizzazione, non vengono mai restituiti. Senza org_id la vista copre ogni record dell'utente nell'ambiente.

Richiesta

Parametro In Obbligatorio Descrizione
user_id percorso sì ID utente, con prefisso usr_.
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 esso o successivi. Deve rientrare nella finestra di conservazione.
to query no Orario RFC 3339; record precedenti ad esso. 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.
org_id query no ID organizzazione, con prefisso org_. Limita la vista ai record di quell'organizzazione; vedi Ambito dell'organizzazione. Richiede organizations:read.

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

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 se la chiave ha l'autorizzazione audit-events:read_ip, e identifier_hint solo se 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 di type, org_id malformato, parametro ripetuto).
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha l'autorizzazione logs:read, oppure org_id è impostato e la chiave non ha organizations:read. required_permissions elenca ciò che la richiesta richiede.
404 not_found L'ID utente è malformato, oppure org_id è impostato e l'utente non è membro di quell'organizzazione.
429 rate_limited È stato superato il limite di richieste; rispetta Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova più tardi.

Esempio

curl "https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/logs?limit=50" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

Solo i record di un'organizzazione:

keenauth users logs list usr_0a1b2c3d4e5f6g7h8j9k0m1n2p --org-id org_01j9xk3m7q8r2s4t6v8w0y2z4d --type authentication.

Dati personali

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