# Utilisateurs

> Lister, créer, modifier, désactiver, supprimer et importer les utilisateurs des clients de votre application par l'API publique.

Un utilisateur est une fiche qui appartient à un seul [client](/v1.0/glossaire#client) et à un seul environnement ; son adresse e-mail est unique par client et par environnement. La même personne peut avoir une fiche en dev, en staging et en prod : trois fiches indépendantes, chacune avec son WID, son compte Keycloak et son [profil](/v1.0/glossaire#profil). Pour faire venir un nouvel utilisateur qui choisira lui-même son mot de passe, préférez une [invitation](/v1.0/reference-api/invitations).

**Accès commun** : appelant de niveau Administrateur client (`CUSTOMER_ADMIN`) au minimum, avec le droit applicatif indiqué. L'appelant n'agit que sur les utilisateurs de son périmètre.

**Environnement de l'appelant** : toutes ces routes n'agissent que sur les fiches de l'environnement de l'appelant, déduit de sa session (claim `wenv` du jeton) ou de sa clé API. Vous ne le fournissez jamais : `env`, `envType` et `envs` sont refusés en `400` `Environment is deduced from the caller and cannot be provided`. Un jeton sans environnement est refusé en `401`, une clé sans environnement en `403`.

## L'objet Utilisateur

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant technique de la fiche, propre à son environnement |
| `wid` | chaîne (6) | Identifiant court de la fiche, propre à son environnement |
| `envType` | chaîne | Environnement de la fiche : `dev`, `staging` ou `prod` |
| `customerId` | UUID | Client de l'utilisateur |
| `email` | chaîne (255) | E-mail, enregistré en minuscules ; unique par client et par environnement |
| `firstName`, `lastName` | chaîne (100) ou `null` | Prénom et nom |
| `adminLevel` | chaîne | `PARTNER_ADMIN`, `APP_ADMIN`, `NETWORK_ADMIN`, `CUSTOMER_ADMIN`, `USER` ou `NONE` (défaut) |
| `hdsRoles` | tableau de chaînes | Rôles HDS |
| `isActive` | booléen | Compte actif (défaut `true`) |
| `keycloakId` | chaîne ou `null` | Identifiant du compte Keycloak de la fiche, sur l'instance de son environnement |
| `lastLoginAt` | chaîne ISO 8601 ou `null` | Dernière connexion |
| `createdAt`, `updatedAt` | chaîne ISO 8601 | Dates de création et de modification |

## Lister les utilisateurs

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

**Droit requis** : `users.read`.

| Paramètre de requête | Type | Défaut | Description |
|---|---|---|---|
| `page` | entier ≥ 1 | 1 | Page |
| `limit` | entier, 1 à 100 | 20 | Taille de page |
| `customerWid`, `customerId` | WID ou UUID | — | Restreint à un client |
| `networkWid`, `networkId` | WID ou UUID | — | Restreint à un réseau |
| `profileId` | UUID | — | Utilisateurs qui portent ce profil |
| `teamId` | UUID | — | Membres de cette équipe |
| `isActive` | booléen | — | `true` ou `false` |
| `include` | chaîne | — | Relations à joindre, séparées par des virgules |

```bash
curl -s "https://api.wakastart.app/api/config/users?customerWid=EXCLI1&isActive=true&limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
{
  "data": [
    {
      "id": "e5f7a9b1-4d6e-4f80-9b2c-3d4e5f6a7b80",
      "wid": "EXUSR1",
      "customerId": "c3d5e7f9-2b4c-4d6e-9f0a-1b2c3d4e5f60",
      "email": "alice@clinique-exemple.fr",
      "firstName": "Alice",
      "lastName": "Martin",
      "adminLevel": "CUSTOMER_ADMIN",
      "hdsRoles": [],
      "isActive": true,
      "envType": "prod",
      "lastLoginAt": "2026-10-23T08:55:10.000Z",
      "createdAt": "2026-03-02T10:14:00.000Z",
      "updatedAt": "2026-09-14T16:02:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 }
}
```

Pour un appel par clé API, les filtres de portée sont remplacés par la portée de la clé. Une clé sans portée reçoit `403` `API key without tenant scope cannot list tenant data`.

## Rechercher un utilisateur par e-mail

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

**Droit requis** : `users.read`. Renvoie la ou les fiches qui portent cette adresse (comparaison exacte, 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.

| Paramètre de requête | Type | Obligatoire | Description |
|---|---|---|---|
| `email` | chaîne | oui | Adresse recherchée |

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

**Réponse `200`**

```json
{
  "items": [
    { "id": "e5f7a9b1-4d6e-4f80-9b2c-3d4e5f6a7b80", "wid": "EXUSR1", "email": "alice@clinique-exemple.fr", "envType": "prod", "isActive": true }
  ]
}
```

Une adresse inconnue renvoie `{ "items": [] }`. **Erreurs** : `400` pour une adresse invalide ou un paramètre d'environnement.

## Lire un utilisateur

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

**Droit requis** : `users.read`. `wid` : identifiant court de la fiche dans l'environnement de l'appelant. Réponse : l'objet Utilisateur. Le WID d'une fiche d'un autre environnement répond `404`.

**Erreurs** : `400` `Validation failed (wid must be a valid WID - 6 alphanumeric characters)` ; `403` `User not found or not accessible` ; `404` `User with WID <wid> not found`.

## Compter les utilisateurs

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

**Droit requis** : `users.stats`.

| Paramètre de requête | Type | Description |
|---|---|---|
| `customerWid` | WID | Client à compter. En dessous du niveau Administrateur réseau, c'est toujours le client de l'appelant qui est compté |

**Réponse `200`**

```json
{ "totalUsers": 128, "activeUsersLast30Days": 74 }
```

## Créer un utilisateur

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

**Droit requis** : `users.create`. Crée la fiche dans l'environnement de l'appelant, et le compte Keycloak sur l'instance de cet environnement. Pour la même personne dans un autre environnement, refaites l'appel avec un jeton ou une clé de cet environnement : il n'existe ni copie ni promotion.

| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
| `email` | chaîne | oui | E-mail, 255 caractères au plus | Unique par client et par environnement |
| `customerId` ou `customerWid` | UUID ou WID | non | — | Client de l'utilisateur. En dessous du niveau Administrateur réseau, c'est toujours le client de l'appelant |
| `firstName`, `lastName` | chaîne | non | 100 caractères au plus | |
| `adminLevel` | chaîne | non | Au plus le niveau de l'appelant | Défaut `NONE` |
| `hdsRoles` | tableau | non | Seulement des rôles que l'appelant possède | Rôles HDS |
| `profileWid` ou `profileId` | WID ou UUID | non | Profil de l'application | Profil attribué à la fiche ; préférez le WID |
| `temporaryPassword` | chaîne | non | 8 caractères au moins | Mot de passe à changer à la première connexion |
| `password` | chaîne | non | 8 caractères au moins | Mot de passe définitif |
| `requireEmailVerification` | booléen | non | — | Demande la vérification de l'e-mail. Défaut `true` |
| `isActive` | booléen | non | — | Défaut `true` |

```bash
curl -s -X POST https://api.wakastart.app/api/config/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "bruno@clinique-exemple.fr",
    "firstName": "Bruno",
    "lastName": "Petit",
    "profileWid": "EXPRO2",
    "requireEmailVerification": true
  }'
```

**Réponse `201`** : l'objet Utilisateur créé.

**Erreurs**

| Statut | Message |
|---|---|
| `403` | `Cannot assign adminLevel <niveau>: exceeds caller privilege ceiling (<niveau>)` |
| `403` | `Cannot assign hdsRole <rôle>: caller does not possess this role` |
| `400` | `Environment is deduced from the caller and cannot be provided` : `envs`, `envType` ou `env` envoyé |
| `409` | `Un utilisateur <email> existe déjà pour ce client dans l'environnement <env>` |
| `503` | `Impossible de joindre l'instance Keycloak [<env>] pour vérifier <email> : <détail>. Réessayez.` |

## Modifier un utilisateur

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

**Droit requis** : `users.update`. Champs modifiables, tous facultatifs : `firstName`, `lastName`, `adminLevel`, `hdsRoles`, `isActive`, `profileId`. Les mêmes plafonds qu'à la création s'appliquent. `profileId` ajoute le profil à la fiche, dans son environnement, sans retirer ceux déjà attribués. Seule la fiche de l'environnement de l'appelant est modifiée.

```bash
curl -s -X PUT https://api.wakastart.app/api/config/users/EXUSR2 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "lastName": "Petit-Durand" }'
```

Réponse : l'objet Utilisateur modifié.

## Désactiver ou réactiver un utilisateur

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

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

**Droit requis** : `users.disable`, pour les deux opérations. Sans corps. La désactivation bloque la connexion de l'utilisateur dans cet environnement et révoque immédiatement ses jetons enrichis ; ses données sont conservées. La réactivation lui rend l'accès. Les fiches de la même personne dans les autres environnements ne sont pas touchées.

```bash
curl -s -X PATCH https://api.wakastart.app/api/config/users/EXUSR2/disable \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Supprimer un utilisateur

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

**Droit requis** : `users.delete`. Supprime définitivement la fiche de l'environnement de l'appelant et son compte Keycloak de cet environnement ; les autres fiches de la personne sont conservées. Préférez la désactivation si vous devez garder l'historique.

**Erreurs** : `409` `Impossible de supprimer cet utilisateur car il possède encore des profils…` ou `… appartient encore à des équipes…` : retirez d'abord ses profils et ses équipes.

## Lister les membres d'une organisation

::endpoint{method="GET" path="/api/admin/org/{orgId}/users"}

**Accès** : Administrateur client de cette organisation, ou administrateur réseau ou d'applications de son réseau. Renvoie les comptes de l'organisation Keycloak du client dans l'environnement de votre session ou de votre clé API, avec leur dernière connexion et leurs profils par application dans cet environnement.

| Paramètre | Où | Type | Défaut | Description |
|---|---|---|---|---|
| `orgId` | chemin | UUID ou WID | — | Client |
| `page` | requête | entier ≥ 1 | 1 | Page |
| `perPage` | requête | entier, 1 à 100 | 20 | Taille de page |
| `search` | requête | chaîne | — | Recherche dans l'e-mail, le prénom et le nom |
| `filterApp` | requête | WID | — | Restreint aux profils d'une application |

**Réponse `200`**

```json
{
  "items": [
    {
      "userId": "6c1f2a9e-4b1d-4e0b-9a51-2f6c3d7e8a10",
      "keycloakId": "6c1f2a9e-4b1d-4e0b-9a51-2f6c3d7e8a10",
      "email": "alice@clinique-exemple.fr",
      "firstName": "Alice",
      "lastName": "Martin",
      "enabled": true,
      "lastLogin": "2026-10-23T08:55:10.000Z",
      "profiles": [{ "appId": "EXAPP1", "appName": "Mon App", "profileId": "EXPRO1", "profileName": "Responsable" }]
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 20
}
```

**Erreurs** : `403` `Access denied: org mismatch` ; `404` `Organization <orgId> not found`.

## Importer des utilisateurs par fichier CSV

:::important
L'import crée les fiches dans l'environnement de l'appelant, avec leur compte Keycloak sur l'instance de cet environnement, mais **sans profil** : attribuez-en un ensuite. Sans environnement déductible, l'import est refusé.
:::

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

**Droit requis** : `users.read`. Renvoie le fichier modèle `import-users-template.csv`, de type `text/csv` :

```csv
email,firstName,lastName,adminLevel
```

::endpoint{method="POST" path="/api/import/users"}

**Droit requis** : `users.import`. Authentifiez l'appel avec un jeton Keycloak ou une clé API. Chaque import consomme des [crédits](/v1.0/reference-api/credits) (opération `IMPORT_USERS`, 2 crédits par défaut).

| Paramètre | Où | Type | Obligatoire | Contraintes |
|---|---|---|---|---|
| `customerId` | requête | UUID | oui | Votre propre client |
| `file` | corps `multipart/form-data` | fichier | oui | CSV, 2 Mo et 500 lignes au plus |

Colonnes : `email` (obligatoire), `firstName`, `lastName`, `adminLevel` (`CUSTOMER_ADMIN`, `USER` ou `NONE`, au plus le niveau de l'appelant ; les niveaux au-delà du client sont refusés). Les lignes en erreur sont ignorées ; les autres sont importées.

```bash
curl -s -X POST "https://api.wakastart.app/api/import/users?customerId=c3d5e7f9-2b4c-4d6e-9f0a-1b2c3d4e5f60" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "file=@utilisateurs.csv;type=text/csv"
```

**Réponse `201`**

```json
{
  "total": 3,
  "successCount": 2,
  "errorCount": 1,
  "created": [
    { "line": 2, "email": "chloe@clinique-exemple.fr", "wid": "EXUSR3" },
    { "line": 3, "email": "david@clinique-exemple.fr", "wid": "EXUSR4" }
  ],
  "errors": [{ "line": 4, "email": "alice@clinique-exemple.fr", "error": "User already exists (skipped to avoid duplicate)" }]
}
```

**Erreurs**

| Statut | Message |
|---|---|
| `400` | `Environment cannot be deduced: import requires the caller environment` |
| `400` | `Seuls les fichiers CSV sont acceptes` |
| `400` | `Fichier CSV requis` |
| `400` | `Le fichier CSV est vide` |
| `400` | `Le fichier CSV contient <n> lignes, maximum autorise: 500` |
| `400` | `Erreur de parsing CSV: <détail>` |
| `402` | `Insufficient credits` |
| `403` | `Vous ne pouvez importer que dans votre propre customer` |
| `413` | `File too large` |

Erreurs possibles par ligne, dans `errors` : `Email requis`, `Format email invalide`, `adminLevel invalide: <valeur>…`, `adminLevel <valeur> depasse votre niveau d'administration`, `User already exists (skipped to avoid duplicate)`.
