# Lister les utilisateurs

> Lister et filtrer les utilisateurs de vos clients dans un environnement, retrouver une fiche par e-mail, consulter une fiche et compter les actifs.

Récupérez la liste des utilisateurs pour l'afficher dans votre propre écran d'administration ou la synchroniser avec un autre outil. Chaque appelant ne voit que les utilisateurs de son périmètre (son client pour un administrateur client, ses réseaux pour un administrateur réseau), et seulement les fiches de **son environnement** : celui de sa session, ou celui de sa clé API.

## Avant de commencer

Vous appelez l'API avec une [clé API](/v1.0/cles-api) ou le jeton d'un administrateur, de niveau Administrateur client au moins, avec le droit `users.read`. Utilisez une clé ou une session de l'environnement dont vous voulez les utilisateurs : une clé de dev ne liste que les fiches de dev.

## Lister et filtrer

::endpoint{method="GET" path="/api/config/users"}

| Paramètre | Description |
|---|---|
| `page`, `limit` | Pagination : page à partir de 1, de 1 à 100 éléments (20 par défaut) |
| `customerWid`, `networkWid` | Restreint à un client ou à un réseau de votre périmètre |
| `isActive` | `true` pour les actifs, `false` pour les désactivés |
| `profileId`, `teamId` | Utilisateurs d'un profil ou d'une équipe (UUID) |
| `include` | `profiles`, `teams` ou `profiles,teams` pour joindre profils et équipes |

```bash
curl "https://api.wakastart.app/api/config/users?customerWid=Cu9pL2&isActive=true&include=profiles&page=1&limit=50" \
  -H "x-api-key: sk_test_exemple"
```

```ts
const params = new URLSearchParams({
  customerWid: "Cu9pL2",
  isActive: "true",
  include: "profiles",
  page: "1",
  limit: "50",
});
const response = await fetch(`https://api.wakastart.app/api/config/users?${params}`, {
  headers: { "x-api-key": process.env.WAKASTART_API_KEY! },
});
const { data, meta } = await response.json();
```

Réponse attendue (extrait) :

```json
{
  "data": [
    {
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
      "wid": "Us2mK6",
      "email": "paul.martin@cabinet-exemple.fr",
      "firstName": "Paul",
      "lastName": "Martin",
      "adminLevel": "USER",
      "isActive": true,
      "envType": "prod"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}
```

La liste est triée par adresse e-mail. Le champ `id` (UUID) sert à ajouter l'utilisateur à une équipe ; le `wid` sert aux autres opérations. Les deux sont propres à la fiche, donc à son environnement.

Le paramètre `envType` n'existe plus : il est refusé en `400` (`Environment is deduced from the caller and cannot be provided`), comme `env`.

## Retrouver un utilisateur par e-mail

::endpoint{method="GET" path="/api/config/users/search"}

Cette route renvoie la ou les fiches qui portent exactement cette adresse (sans tenir compte de la casse), dans votre périmètre et dans l'environnement de l'appelant : au plus une par client. Une fiche d'un autre environnement n'est jamais renvoyée. Utilisez-la pour rattacher un compte de votre application à sa fiche Wakastart sans stocker de WID.

```bash
curl "https://api.wakastart.app/api/config/users/search?email=paul.martin@cabinet-exemple.fr" \
  -H "x-api-key: sk_test_exemple"
```

```ts
const response = await fetch(
  `https://api.wakastart.app/api/config/users/search?email=${encodeURIComponent("paul.martin@cabinet-exemple.fr")}`,
  { headers: { "x-api-key": process.env.WAKASTART_API_KEY! } },
);
const { items } = await response.json();
```

Réponse attendue (extrait) :

```json
{
  "items": [
    { "wid": "Us2mK6", "email": "paul.martin@cabinet-exemple.fr", "envType": "prod" }
  ]
}
```

N'envoyez que `email` : le périmètre et l'environnement sont déduits de l'appelant. Une adresse invalide répond `400` ; une adresse inconnue renvoie `{ "items": [] }`.

## Consulter un utilisateur

::endpoint{method="GET" path="/api/config/users/{wid}"}

```bash
curl "https://api.wakastart.app/api/config/users/Us2mK6" \
  -H "x-api-key: sk_test_exemple"
```

Réponse attendue : la fiche de l'utilisateur, avec son client, son réseau, ses profils et ses droits. Un utilisateur hors de votre périmètre renvoie 403 ; le WID d'une fiche d'un autre environnement renvoie 404.

## Compter les utilisateurs actifs

::endpoint{method="GET" path="/api/config/users/stats"}

Le droit `users.stats` est requis. Un administrateur client obtient toujours les chiffres de son propre client.

```bash
curl "https://api.wakastart.app/api/config/users/stats?customerWid=Cu9pL2" \
  -H "x-api-key: sk_test_exemple"
```

Réponse attendue :

```json
{ "totalUsers": 42, "activeUsersLast30Days": 31 }
```

Un utilisateur est compté comme actif s'il s'est connecté dans les 30 derniers jours.

## Vérifier le résultat

Le `total` de `meta` correspond au nombre de fiches de votre périmètre, dans votre environnement, qui passent les filtres. Comparez-le à `totalUsers` pour un client sans filtre.

## Voir aussi

- [Gérer un utilisateur](/v1.0/utilisateurs/gerer-un-utilisateur)
- [Référence API des utilisateurs](/v1.0/reference-api/utilisateurs)
