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 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. Pour faire venir un nouvel utilisateur qui choisira lui-même son mot de passe, préférez une invitation.
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
/api/config/usersDroit 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 |
curl -s "https://api.wakastart.app/api/config/users?customerWid=EXCLI1&isActive=true&limit=50" \
-H "Authorization: Bearer $ACCESS_TOKEN"Réponse 200
{
"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
/api/config/users/searchDroit 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 |
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
{
"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
/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
/api/config/users/statsDroit 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
{ "totalUsers": 128, "activeUsersLast30Days": 74 }Créer un utilisateur
/api/config/usersDroit 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 |
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
/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.
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
/api/config/users/{wid}/disable/api/config/users/{wid}/enableDroit 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.
curl -s -X PATCH https://api.wakastart.app/api/config/users/EXUSR2/disable \
-H "Authorization: Bearer $ACCESS_TOKEN"Supprimer un utilisateur
/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
/api/admin/org/{orgId}/usersAccè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
{
"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é.
/api/import/users/templateDroit requis : users.read. Renvoie le fichier modèle import-users-template.csv, de type text/csv :
email,firstName,lastName,adminLevel/api/import/usersDroit requis : users.import. Authentifiez l'appel avec un jeton Keycloak ou une clé API. Chaque import consomme des crédits (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.
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
{
"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).