# Lister les événements

`GET /v1/events` · autorisation `events:read`

Renvoie les événements de l'environnement, dans l'ordre, du plus ancien au plus récent. Chaque événement est le même document, avec le même `id`, que celui livré par les webhooks. Les événements sont conservés pendant 30 jours sur toutes les offres.

Utilisez ce point de terminaison lorsque votre système ne peut pas recevoir de webhooks, ou pour combler un manque après une panne : conservez le dernier `next_cursor` que vous avez traité et poursuivez à partir de celui-ci.

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

## Requête

| Paramètre | Emplacement | Obligatoire | Description |
|---|---|---|---|
| `after` | query | non | `next_cursor` de la réponse précédente, ou `latest` pour ne recevoir que les événements enregistrés à partir de maintenant. Sans ce paramètre, la liste commence au plus ancien événement conservé. |
| `types` | query | non | Types d'événements séparés par des virgules, 20 au maximum, par exemple `user.created,user.deleted`. Sans ce paramètre, tous les types sont renvoyés. |
| `org_id` | query | non | Seulement les événements de cette organisation (`org_…`). |
| `limit` | query | non | Taille de page, de 1 à 100. Par défaut 20. |
| `payload` | query | non | `thin` (par défaut) ou `full`. `full` nécessite également l'autorisation `users:read`. Tant que la charge utile complète n'est pas disponible, `full` renvoie la charge utile réduite. |
| `purpose` | query | non | `tail` (par défaut) ou `webhooks_listen`. `webhooks_listen` n'est accepté que dans les environnements `development` et `staging`. |

## Réponse

`200 OK` :

| Champ | Description |
|---|---|
| `data` | Événements dans l'ordre. Chaque événement possède un `seq` qui augmente au sein de l'environnement. |
| `next_cursor` | Toujours présent. Transmettez-le comme `after` dans la requête suivante, même lorsque `data` est vide. |
| `has_more` | `true` lorsque d'autres événements suivent ; relancez la requête immédiatement. Lorsque la valeur est `false`, attendez avant d'interroger à nouveau (5 à 60 secondes). |

Le curseur ne dépend pas de `types` ni de `org_id` : vous pouvez modifier le filtre et poursuivre à partir de la même position. Un curseur ne fonctionne que dans l'environnement qui l'a émis.

```json
{
  "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
}
```

## Exemple : interroger les nouveaux événements

```bash
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 effectue la même opération avec `keenauth events tail`.

## Erreurs

Chaque erreur est un corps `application/problem+json` accompagné d'un `code` stable.

| HTTP | `code` | Quand |
|---|---|---|
| 400 | `invalid_cursor` | Le curseur est mal formé ou a été émis dans un autre environnement. |
| 401 | `unauthenticated` | La clé d'API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne possède pas `events:read`, ou `payload=full` est demandé sans `users:read`. |
| 403 | `test_feature_not_in_production` | `purpose=webhooks_listen` dans un environnement de production. |
| 422 | `validation_failed` | Un paramètre est invalide ou répété ; `errors[].pointer` l'indique. |
| 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. |

## Données personnelles

Ce point de terminaison traite des données personnelles : les événements. [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit ce qui est stocké, pendant combien de temps les données sont conservées et comment elles sont supprimées. N'envoyez de catégories particulières de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.