# Lister les utilisateurs du répertoire

`GET /v1/directories/{directory_id}/users` · autorisation `directories:read`

Liste les enregistrements d'utilisateurs actifs que le fournisseur d'identité a provisionnés dans le répertoire, classés par ID : les attributs normalisés, les groupes du répertoire de l'utilisateur, le lien vers l'utilisateur de l'environnement et l'indicateur de dérive. Les enregistrements supprimés ne sont pas renvoyés. Les filtres `state` et `group_id` peuvent être combinés. Seule la pagination vers l'avant existe ; le curseur est lié au répertoire et aux filtres.

Sans l'autorisation `users:read_pii`, l'identifiant reçoit des données personnelles masquées : `user_name` sous la forme de son premier caractère suivi de `***`, `emails[].value` sous la forme `a***@e***.com`, `given_name`, `family_name` et `display_name` sous forme d'initiales, et `attributes` à `null`. `external_id`, `locale`, `zoneinfo`, les groupes et les ID ne sont jamais masqués. Une clé secrète dispose de toutes les autorisations.

## Requête

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `directory_id` | path | oui | ID du répertoire SCIM (`dir_…`). |
| `state` | query | non | Seulement les utilisateurs dans cet état : `active`, `inactive` ou `held` (dans un blocage de désactivation en masse). |
| `group_id` | query | non | Seulement les membres de ce groupe du répertoire (`dsg_…`) ; un groupe d'un autre répertoire renvoie une page vide. |
| `limit` | query | non | 1–100, valeur par défaut 20. |
| `after` | query | non | Le curseur issu de `list_metadata.after`. |

Il n'y a pas de corps de requête.

## Réponse

`200 OK` avec une page d'utilisateurs du répertoire.

```json
{
  "data": [
    {
      "id": "dsu_01j9xp4q6r8s0t2v4w6x8y0z2b",
      "directory_id": "dir_01j9xm2n4p6q8r0s2t4v6w8y0z",
      "external_id": "00u1a2b3c4",
      "user_name": "jane@example.com",
      "emails": [{ "value": "jane@example.com", "primary": true }],
      "given_name": "Jane",
      "family_name": "Doe",
      "display_name": "Jane Doe",
      "locale": "en-US",
      "zoneinfo": "Europe/Berlin",
      "state": "active",
      "attributes": { "department": "Engineering" },
      "groups": [{ "id": "dsg_01j9xn3p5q7r9s1t3v5w7x9y1a", "name": "Engineering" }],
      "user_id": "usr_01j9xq5r7s9t1v3w5x7y9z1a3c",
      "link_status": "linked",
      "drift": false,
      "created_at": "2026-10-20T09:00:00Z",
      "updated_at": "2026-10-20T09:05:00Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}
```

`link_status` vaut l'une des valeurs suivantes : `linked`, `invited`, `blocked_other_org`, `duplicate`, `mirror_only` ou `unlinked` ; `user_id` vaut `null` lorsque l'enregistrement n'est pas lié. Les valeurs vides sont `null`.

## Erreurs

| HTTP | code | Quand |
|---|---|---|
| 400 | `invalid_cursor` | Le curseur est invalide ou appartient à un autre répertoire ou à un autre filtre. |
| 404 | `not_found` | Le répertoire n'existe pas dans cet environnement. |
| 422 | `validation_failed` | `state` ou `group_id` est invalide ou répété, `limit` est hors plage, ou `before` ou `order` a été fourni (`unsupported`). |
| 401 | `unauthenticated` | L'identifiant est absent, invalide ou révoqué. |
| 403 | `insufficient_permissions` | L'identifiant ne dispose pas de l'autorisation requise. |
| 429 | `rate_limited` | La limite de débit a été dépassée ; réessayez après la période indiquée par `Retry-After`. |
| 503 | `service_unavailable` | La synchronisation des répertoires est temporairement indisponible ou non configurée dans ce déploiement ; réessayez après la période indiquée par `Retry-After`. |

## Exemple

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

## Données personnelles

Ce point de terminaison traite des données personnelles : des utilisateurs de répertoire (SCIM). [Données personnelles dans les API KeenAuth](/docs/policies/personal-data) décrit ce qui est stocké, combien de temps ces 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.