Lister les événements d'audit

GET /v1/audit-events · autorisation audit-events:read

Liste les enregistrements d'audit de l'environnement avec une pagination par curseur, du plus récent au plus ancien. Le flux admin contient les modifications effectuées via l'API de gestion, le tableau de bord et la plateforme ; le flux application contient les événements écrits par votre application. Chaque enregistrement fait partie d'une chaîne de hachage par environnement et par flux, de sorte que l'historique peut être vérifié indépendamment à l'aide d'un export (POST /v1/audit-exports).

L'environnement provient toujours de la clé API ; il n'existe pas de paramètre d'environnement.

Requête

Paramètre	Dans	Obligatoire	Description
`limit`	query	non	Taille de page, de 1 à 100. Valeur par défaut : 20.
`after`	query	non	Curseur opaque issu de `list_metadata.after` (enregistrements plus anciens). Exclusif avec `before`.
`before`	query	non	Curseur opaque issu de `list_metadata.before` (enregistrements plus récents). Exclusif avec `after`.
`stream`	query	non	`admin` (par défaut) ou `application`.
`from`	query	non	Heure RFC 3339 ; enregistrements à cette heure ou après. Par défaut, la plus tardive entre le début de la fenêtre de conservation et `to` moins 92 jours.
`to`	query	non	Heure RFC 3339 ; enregistrements antérieurs à cette heure. Par défaut, maintenant. La plage de `from` à `to` ne dépasse pas 92 jours.
`action`	query	non	Préfixe d'action, tel que `user.` ou `connection.updated`.
`category`	query	non	`authentication`, `session`, `token`, `administration`, `provisioning`, `federation`, `authorization`, `data_access`, `security`, `key_management`, `configuration` ou `application`.
`actor_type`	query	non	Type d'acteur, tel que `api_key`, `dashboard_user`, `m2m_client`, `agent` ou `system`.
`actor_id`	query	non	Identifiant exact de l'acteur tel qu'enregistré (`key_…`, `usr_…`, `system:<service>`).
`target_type`	query	non	Type de cible, tel que `user`, `organization` ou `audit_export`.
`target_id`	query	non	Identifiant exact de la cible. Avec `target_type`, les deux doivent correspondre à la même cible.
`org_id`	query	non	Enregistrements concernant une organisation (`org_…`).
`outcome`	query	non	`success`, `failure`, `denied` ou `error`.
`request_id`	query	non	`Idp-Request-Id` d'une requête (UUID).
`correlation_id`	query	non	`Idp-Correlation-Id` d'un workflow (UUID).
`agent_only`	query	non	`true` ne renvoie que les actions d'agents : `actor_type` `agent` ou un `act_chain` non vide.
`client`	query	non	Type de client ayant effectué l'appel : `mcp` (le serveur MCP de gestion, `metadata.client` = `mcp/<version>`) ou `cli` (la CLI KeenAuth, `cli/<version>`). Le client déclare lui-même cette valeur ; elle ne prouve pas qui a agi, c'est l'acteur de l'enregistrement qui le fait. Liste uniquement : un export n'a pas de filtre `client`.

Les enregistrements sont toujours triés par occurred_at (puis id), du plus récent au plus ancien ; il n'existe pas de paramètre order (order=desc est accepté, toute autre valeur échoue avec validation_failed). Un curseur n'est valide qu'avec les filtres et l'environnement pour lesquels il a été émis. Aucun nombre total n'est renvoyé.

Une recherche dépassant 10 secondes s'interrompt avec 422 search_too_broad : restreignez les filtres ou la plage de temps, ou utilisez un export pour les plages étendues.

Réponse

200 OK. data contient les enregistrements de la page ; list_metadata.after pointe vers les enregistrements plus anciens et list_metadata.before vers les plus récents (null lorsqu'il n'y en a pas). Les champs vides valent null.

ip et user_agent ne sont présents que si la clé possède l'autorisation audit-events:read_ip, et ne sont renseignés que pour les enregistrements de moins de 13 mois. Sans cette autorisation, les champs sont entièrement omis (aucune valeur masquée). ip_prefix, ip_country, ip_asn et user_agent_family sont toujours renvoyés. prev_hash, org_prev_hash et record_hash sont des valeurs SHA-256 en base64url sans remplissage.

{
  "data": [
    {
      "id": "evt_01j9xk3m7q8r2s4t6v8w0y2z4a",
      "stream": "admin",
      "seq": 4182,
      "schema_version": 1,
      "action": "user.blocked",
      "category": "administration",
      "outcome": "success",
      "reason_code": null,
      "occurred_at": "2026-10-01T08:15:42.120Z",
      "received_at": "2026-10-01T08:15:42.131Z",
      "recorded_at": "2026-10-01T08:15:42.140Z",
      "clock_anomaly": false,
      "actor_type": "api_key",
      "actor_id": "key_01j9xk3m7q8r2s4t6v8w0y2z4d",
      "act_chain": null,
      "session_id": null,
      "auth_context": null,
      "elevation_ref": null,
      "org_id": null,
      "targets": [
        {"type": "user", "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p", "org_id": null, "name": null}
      ],
      "application_id": null,
      "ip_prefix": "203.0.113.0/24",
      "ip_country": "DE",
      "ip_asn": 64500,
      "user_agent_family": "keenauth-go",
      "request_id": "0192a6c1-7d3e-7a10-9b2c-3d4e5f607182",
      "correlation_id": null,
      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
      "producer_service": "directory",
      "policy_ref": "perm:users:write",
      "changes": {"status": {"old": "active", "new": "blocked"}},
      "metadata": null,
      "prev_hash": "n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg",
      "org_prev_hash": null,
      "record_hash": "LCa0a2j_xo_5m0U8HTBBNBNCLXBkg7-g-YpeiGJm564"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": "<opaque cursor>"
  }
}

Erreurs

Chaque erreur est un corps application/problem+json avec un code stable.

HTTP	`code`	Quand
400	`invalid_cursor`	Le curseur est mal formé ou n'a pas été émis pour cette requête.
400	`invalid_filter`	Le service d'audit a rejeté un filtre, par exemple une plage de plus de 92 jours.
400	`range_outside_retention`	`from` ou `to` est en dehors de la fenêtre de conservation des audits de votre offre.
422	`validation_failed`	Un paramètre de requête est invalide (`limit` hors plage, horodatage incorrect, `to` non postérieur à `from`, `stream`, `category` ou `outcome` inconnu, identifiant mal formé, paramètre répété, `order` autre que `desc`).
422	`search_too_broad`	La recherche a dépassé 10 secondes ; restreignez-la.
401	`unauthenticated`	La clé API est absente, invalide ou révoquée.
403	`insufficient_permissions`	La clé ne possède pas `audit-events:read`.
429	`rate_limited`	La limite de débit a été dépassée ; respectez `Retry-After`.
503	`service_unavailable`	Une dépendance est temporairement indisponible ; réessayez plus tard.

Exemple

curl "https://api.eu.keenauth.com/v1/audit-events?action=user.&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

keenauth audit-events list --action user. --from 2026-10-01T00:00:00Z

Données personnelles

Ce point de terminaison traite des données personnelles : des événements d'audit. Données personnelles dans les API KeenAuth décrit ce qui est stocké, pendant combien de temps il est conservé et comment il est supprimé. Ne transmettez de catégories particulières de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.