# Lister les utilisateurs

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

Liste les utilisateurs de l'environnement avec une pagination par curseur, les plus récents en premier par défaut. Seuls les filtres ne contenant aucune donnée personnelle sont acceptés ici. Pour rechercher des utilisateurs par adresse e-mail, numéro de téléphone ou nom d'utilisateur, utilisez [Rechercher des utilisateurs](/docs/api/management/users/search).

## Requête

| Paramètre | Dans | Requis | Description |
|---|---|---|---|
| `limit` | query | non | Taille de page, de 1 à 100. Par défaut 20. |
| `after` | query | non | Curseur opaque issu de `list_metadata.after`. Exclusif avec `before`. |
| `before` | query | non | Curseur opaque issu de `list_metadata.before`. Exclusif avec `after`. |
| `order` | query | non | `asc` ou `desc` selon la date de création. Par défaut `desc`. |
| `status` | query | non | `active`, `blocked` ou `pending_deletion`. |
| `external_id` | query | non | Correspondance exacte avec votre propre identifiant. |
| `created_after` | query | non | Heure RFC 3339 ; utilisateurs créés après cette heure. |
| `created_before` | query | non | Heure RFC 3339 ; utilisateurs créés avant cette heure. |

Un curseur n'est valable qu'avec les mêmes filtres et le même ordre que ceux pour lesquels il a été émis ; sinon, la requête échoue avec `invalid_cursor`.

## Réponse

`200 OK`. `data` contient les utilisateurs de la page ; `list_metadata.before` et `list_metadata.after` sont les curseurs de la page précédente et de la page suivante (`null` lorsqu'il n'y en a pas). Aucun nombre total n'est renvoyé.

Les données personnelles sont masquées lorsque la clé ne possède pas l'autorisation `users:read_pii` : `email` devient `a***@e***.com`, `phone_number` ne conserve que ses 2 derniers chiffres (`+**********67`), `name`, `given_name`, `family_name`, `middle_name` et `nickname` deviennent des initiales (`A. L.`), `username` ne conserve que son premier caractère (`a***`), `birthdate` devient `****-**-**` et `address` devient `{"redacted": true}`. `user_metadata` et `app_metadata` ne sont pas masqués.

```json
{
  "data": [ {
    "id": "usr_0a1b2c3d4e5f6g7h8j9k0m1n2p",
    "kind": "regular",
    "status": "active",
    "external_id": null,
    "username": null,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "email_verified": true,
    "phone_number": null,
    "phone_verified": false,
    "user_metadata": {},
    "app_metadata": {},
    "created_via": "admin_api",
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z",
    "last_sign_in_at": null,
    "deletion_requested_at": null,
    "deletion_due_at": null
  } ],
  "list_metadata": { "before": null, "after": "<opaque cursor>" }
}
```

## 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é, altéré ou a été émis pour d'autres filtres. |
| 422 | `validation_failed` | Un paramètre de requête est invalide (`limit` hors plage, horodatage incorrect, paramètre répété). |
| 401 | `unauthenticated` | La clé API est absente, invalide ou révoquée. |
| 403 | `insufficient_permissions` | La clé ne possède pas l'autorisation `users: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

```bash
curl "https://api.eu.keenauth.com/v1/users?limit=20&status=active" \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"
```

## Données personnelles

Ce point de terminaison contient des données personnelles : profil de l'utilisateur final. [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit ce qui est stocké, la durée de conservation et la manière dont elles sont supprimées. N'envoyez aucune catégorie particulière de données personnelles (santé, données biométriques, religion, opinions politiques, orientation sexuelle) dans aucun champ.