Elenca eventi

GET /v1/events · autorizzazione events:read

Restituisce gli eventi dell'ambiente in ordine, dal più vecchio. Ogni evento è lo stesso documento, con lo stesso id, che i webhook consegnano. Gli eventi vengono conservati per 30 giorni su ogni piano.

Usa questo endpoint quando il tuo sistema non può ricevere webhook, oppure per colmare una lacuna dopo un'interruzione: conserva l'ultimo next_cursor elaborato e continua da lì.

L'ambiente proviene sempre dalla chiave API; non esiste un parametro dell'ambiente.

Richiesta

Parametro In Obbligatorio Descrizione
after query no next_cursor della risposta precedente, oppure latest per ricevere solo gli eventi registrati da adesso in poi. Senza questo parametro l'elenco parte dall'evento conservato più vecchio.
types query no Tipi di evento separati da virgola, al massimo 20, ad esempio user.created,user.deleted. Senza questo parametro vengono restituiti tutti i tipi.
org_id query no Solo eventi di questa organizzazione (org_…).
limit query no Dimensione della pagina, da 1 a 100. Predefinito 20.
payload query no thin (predefinito) o full. full richiede anche l'autorizzazione users:read. Finché il payload completo non è disponibile, full restituisce il payload thin.
purpose query no tail (predefinito) o webhooks_listen. webhooks_listen è accettato solo negli ambienti development e staging.

Risposta

200 OK:

Campo Descrizione
data Eventi in ordine. Ogni evento ha un seq che cresce all'interno dell'ambiente.
next_cursor Sempre presente. Passalo come after nella richiesta successiva, anche quando data è vuoto.
has_more true quando seguono altri eventi; richiedi di nuovo subito. Quando è false, attendi prima di interrogare di nuovo (da 5 a 60 secondi).

Il cursore non dipende da types o org_id: puoi cambiare il filtro e continuare dalla stessa posizione. Un cursore funziona solo nell'ambiente che lo ha emesso.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "type": "connection.deleted",
      "schema_version": 1,
      "environment_id": "env_01j9xk3m7q8r2s4t6v8w0y2z4e",
      "occurred_at": "2026-11-03T08:15:42.120Z",
      "recorded_at": "2026-11-03T08:15:42.140Z",
      "seq": 4182,
      "data": {
        "object": {"id": "conn_01j9xk3m7q8r2s4t6v8w0y2z4f", "status": "deleted"},
        "object_version": 2
      },
      "context": {"actor": {"type": "system"}, "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182"}
    }
  ],
  "next_cursor": "eyJ2IjoxfQ.c2lnbmF0dXJl",
  "has_more": false
}

Esempio: interroga per nuovi eventi

cursor=latest
while true; do
  page=$(curl -sS -G https://api.keenauth.com/v1/events \
    -H "Authorization: Bearer $KEENAUTH_API_KEY" \
    --data-urlencode "after=$cursor" --data-urlencode "limit=100")
  echo "$page" | jq -c '.data[]'
  cursor=$(echo "$page" | jq -r '.next_cursor')
  [ "$(echo "$page" | jq -r '.has_more')" = "true" ] || sleep 10
done

La CLI fa lo stesso con keenauth events tail.

Errori

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

HTTP code Quando
400 invalid_cursor Il cursore è malformato o è stato emesso in un altro ambiente.
401 unauthenticated La chiave API manca, non è valida o è stata revocata.
403 insufficient_permissions La chiave non ha events:read, oppure payload=full senza users:read.
403 test_feature_not_in_production purpose=webhooks_listen in un ambiente di produzione.
422 validation_failed Un parametro non è valido o è ripetuto; errors[].pointer ne indica il nome.
429 rate_limited È stato superato il limite di frequenza; rispetta Retry-After.
503 service_unavailable Una dipendenza è temporaneamente non disponibile; riprova più tardi.

Dati personali

Questo endpoint trasporta dati personali: eventi. 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.