Aller au contenu

Utilisateurs

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

RéférenceDéveloppeurAdministrateur
Voir en Markdown

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

ChampTypeDescription
idUUIDIdentifiant technique de la fiche, propre à son environnement
widchaîne (6)Identifiant court de la fiche, propre à son environnement
envTypechaîneEnvironnement de la fiche : dev, staging ou prod
customerIdUUIDClient de l'utilisateur
emailchaîne (255)E-mail, enregistré en minuscules ; unique par client et par environnement
firstName, lastNamechaîne (100) ou nullPrénom et nom
adminLevelchaînePARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN, USER ou NONE (défaut)
hdsRolestableau de chaînesRôles HDS
isActivebooléenCompte actif (défaut true)
keycloakIdchaîne ou nullIdentifiant du compte Keycloak de la fiche, sur l'instance de son environnement
lastLoginAtchaîne ISO 8601 ou nullDernière connexion
createdAt, updatedAtchaîne ISO 8601Dates de création et de modification

Lister les utilisateurs

GET/api/config/users

Droit requis : users.read.

Paramètre de requêteTypeDéfautDescription
pageentier ≥ 11Page
limitentier, 1 à 10020Taille de page
customerWid, customerIdWID ou UUID—Restreint à un client
networkWid, networkIdWID ou UUID—Restreint à un réseau
profileIdUUID—Utilisateurs qui portent ce profil
teamIdUUID—Membres de cette équipe
isActivebooléen—true ou false
includechaî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

GET/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êteTypeObligatoireDescription
emailchaîneouiAdresse 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

GET/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

GET/api/config/users/stats

Droit requis : users.stats.

Paramètre de requêteTypeDescription
customerWidWIDClient à 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

POST/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.

ChampTypeObligatoireContraintesDescription
emailchaîneouiE-mail, 255 caractères au plusUnique par client et par environnement
customerId ou customerWidUUID ou WIDnon—Client de l'utilisateur. En dessous du niveau Administrateur réseau, c'est toujours le client de l'appelant
firstName, lastNamechaînenon100 caractères au plus
adminLevelchaînenonAu plus le niveau de l'appelantDéfaut NONE
hdsRolestableaunonSeulement des rôles que l'appelant possèdeRôles HDS
profileWid ou profileIdWID ou UUIDnonProfil de l'applicationProfil attribué à la fiche ; préférez le WID
temporaryPasswordchaînenon8 caractères au moinsMot de passe à changer à la première connexion
passwordchaînenon8 caractères au moinsMot de passe définitif
requireEmailVerificationbooléennon—Demande la vérification de l'e-mail. Défaut true
isActivebooléennon—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

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

Modifier un utilisateur

PUT/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

PATCH/api/config/users/{wid}/disable
PATCH/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

DELETE/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

GET/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ètreOùTypeDéfautDescription
orgIdcheminUUID ou WID—Client
pagerequêteentier ≥ 11Page
perPagerequêteentier, 1 à 10020Taille de page
searchrequêtechaîne—Recherche dans l'e-mail, le prénom et le nom
filterApprequêteWID—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é.

GET/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
POST/api/import/users

Droit 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ètreOùTypeObligatoireContraintes
customerIdrequêteUUIDouiVotre propre client
filecorps multipart/form-datafichierouiCSV, 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

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