Jeton et /me
Lire l'utilisateur connecté, obtenir un jeton enrichi et vérifier les droits d'un utilisateur depuis le serveur de votre application.
Ces endpoints répondent à deux questions : qui est l'utilisateur connecté, et a-t-il le droit de faire une action donnée. Le premier usage, GET /api/me, est appelé par votre application juste après la connexion ; les endpoints /api/token/* servent au serveur de votre application pour contrôler le jeton d'un utilisateur.
L'objet Me
| Champ | Type | Description |
|---|---|---|
wid | chaîne | Identifiant court de la fiche de l'utilisateur dans l'environnement de la session. Une personne présente sur plusieurs environnements a un WID par environnement : ne le stockez pas comme clé durable |
email | chaîne | |
firstName, lastName | chaîne | Prénom et nom, s'ils sont connus |
isActive | booléen | Compte actif |
adminLevel | chaîne | Niveau d'administration : PARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN, USER ou NONE |
hdsRoles | tableau de chaînes | Rôles HDS : HDS_ADMIN, HDS_PATIENT, HDS_HEALTHCARE, HDS_STORAGE, HDS_DELETE, HDS_MEDICAL |
partner | objet { wid, name } | Propriétaire de l'application |
network | objet { wid, name } | Réseau du client |
customer | objet { wid, name } | Client de l'utilisateur |
teams | tableau | Équipes : { wid, name, teamLevel }, teamLevel valant ADMIN, MANAGER, MEMBER, CONTRIBUTOR, VIEWER ou NONE |
profile | objet | Profil de l'utilisateur pour l'environnement de la session : { wid, name, description, rights } |
profile.rights | tableau | Droits applicatifs du profil dans cet environnement : { code, name, description, category } |
branding | objet | Visuels et thème applicables, résolus du client vers le réseau puis l'application : logoLightUrl, logoDarkUrl, bgLightUrl, bgDarkUrl, faviconUrl, primaryColor, accentColor, background, themeName, themeCssPath, themeCssVarsLight, themeCssVarsDark. Les champs sans valeur sont omis |
lastLoginAt | chaîne ISO 8601 | Dernière connexion |
createdAt | chaîne ISO 8601 | Création du compte |
/api/me décrit la fiche de l'environnement de la session (claim wenv du jeton) : il ne prend aucun paramètre d'environnement, et il n'existe pas de lecture « tous environnements ». Si la fiche n'a aucun profil dans cet environnement, profile vaut { "wid": "", "name": "Default", "description": "" } ; l'ancien profil unique de la fiche n'est plus utilisé en repli. Le champ profile.rights est omis quand le profil ne porte aucun droit dans cet environnement.
Lire l'utilisateur connecté
/api/meAccès : tout utilisateur authentifié par jeton Keycloak ou jeton enrichi, sans niveau minimal. Une session sans environnement est refusée en 401 Environment cannot be deduced: session has no environment, sans repli sur la production.
curl -s https://api.wakastart.app/api/me \
-H "Authorization: Bearer $ACCESS_TOKEN"interface Me {
wid: string;
email: string;
adminLevel: string;
customer: { wid: string; name: string };
profile: { wid: string; name: string; rights?: { code: string; name: string }[] };
}
const me = (await fetch("https://api.wakastart.app/api/me", {
headers: { Authorization: `Bearer ${accessToken}` },
}).then((r) => r.json())) as Me;
const canInvite = me.profile.rights?.some((r) => r.code === "invitations.create") ?? false;Réponse 200
{
"wid": "EXUSR1",
"email": "alice@clinique-exemple.fr",
"firstName": "Alice",
"lastName": "Martin",
"isActive": true,
"adminLevel": "CUSTOMER_ADMIN",
"hdsRoles": [],
"customer": { "wid": "EXCLI1", "name": "Clinique Exemple" },
"network": { "wid": "EXNET1", "name": "Réseau Exemple" },
"partner": { "wid": "EXPRT1", "name": "Éditeur Exemple" },
"teams": [{ "wid": "EXTEA1", "name": "Accueil", "teamLevel": "MANAGER" }],
"profile": {
"wid": "EXPRO1",
"name": "Responsable",
"description": "Gère les comptes de la clinique",
"rights": [
{ "code": "users.read", "name": "Voir les utilisateurs", "description": null, "category": "Utilisateurs" },
{ "code": "invitations.create", "name": "Inviter", "description": null, "category": "Utilisateurs" }
]
},
"branding": { "logoLightUrl": "https://mon-app.exemple.fr/logo.svg", "themeName": "clair" },
"lastLoginAt": "2026-10-23T08:55:10.000Z",
"createdAt": "2026-03-02T10:14:00.000Z"
}Erreurs
| Statut | Message | Cause |
|---|---|---|
401 | Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header) | Aucune identité valide dans la requête |
404 | Utilisateur non trouvé | Le compte Keycloak n'a pas de compte Wakastart associé pour cette application |
409 | Impossible de résoudre l'utilisateur de façon unique (customerId manquant ou invalide) | Le même compte appartient à plusieurs clients et le jeton ne permet pas de choisir |
Enrichir un jeton Keycloak
/api/auth/enrichAccès : public ; le jeton Keycloak envoyé dans Authorization fait office de preuve.
Renvoie un jeton enrichi signé par Wakastart, à envoyer ensuite dans l'en-tête x-enriched-token (voir Authentification).
curl -s -X POST https://api.wakastart.app/api/auth/enrich \
-H "Authorization: Bearer $ACCESS_TOKEN"Réponse 200
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI…",
"payload": {
"sub": "6c1f2a9e-4b1d-4e0b-9a51-2f6c3d7e8a10",
"email": "alice@clinique-exemple.fr",
"azp": "EXAPP1",
"wadl": "CUSTOMER_ADMIN",
"pid": "EXPRT1",
"nid": "EXNET1",
"cid": "EXCLI1",
"aid": "EXAPP1",
"uid": "EXUSR1",
"wenv": "prod",
"exp": 1761211064
}
}Principaux champs du jeton enrichi :
| Champ | Description |
|---|---|
sub, email | Identité Keycloak de l'utilisateur |
azp | Client Keycloak de l'application |
wadl | Niveau d'administration |
pid, nid, cid, aid, uid | Identifiants courts du propriétaire, du réseau, du client, de l'application et de l'utilisateur |
wenv | Environnement de la session : dev, staging ou prod |
given_name, family_name | Prénom et nom |
exp | Expiration, en secondes depuis le 1er janvier 1970 |
Erreurs : 401 Missing or invalid Authorization header si l'en-tête est absent ou ne commence pas par Bearer . Un jeton Keycloak expiré ou refusé ne donne pas d'erreur : la réponse est 200 avec un corps vide {}. Vérifiez donc la présence de token avant de l'utiliser.
/api/token/enrichVariante qui reçoit le jeton Keycloak dans le corps, pour un serveur qui ne peut pas poser d'en-tête Authorization. Accès : public. Aucune limite de débit.
| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
token | chaîne | oui | Jeton Keycloak, 10 000 caractères au plus |
curl -s -X POST https://api.wakastart.app/api/token/enrich \
-H 'Content-Type: application/json' \
-d "{\"token\": \"$ACCESS_TOKEN\"}"Réponse 200 : { "token": "eyJ…", "expiresAt": 1761211064 }.
Vérifier le jeton d'un utilisateur
Les endpoints /api/token/* permettent au serveur de votre application de faire contrôler par Wakastart le jeton Keycloak qu'un utilisateur lui présente. Le jeton à contrôler est envoyé dans le corps ; l'appel lui-même est authentifié par votre serveur, en général avec une clé API.
Accès commun : appelant de niveau Administrateur client (CUSTOMER_ADMIN) au minimum.
/api/token/verifyVérifie la signature et la validité du jeton et renvoie l'identité qu'il porte.
| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
token | chaîne | oui | 10 000 caractères au plus |
curl -s -X POST https://api.wakastart.app/api/token/verify \
-H "x-api-key: sk_test_exemple" \
-H 'Content-Type: application/json' \
-d "{\"token\": \"$USER_TOKEN\"}"Réponse 200
{
"sub": "6c1f2a9e-4b1d-4e0b-9a51-2f6c3d7e8a10",
"email": "alice@clinique-exemple.fr",
"iat": 1761210164,
"exp": 1761211064,
"keycloakId": "6c1f2a9e-4b1d-4e0b-9a51-2f6c3d7e8a10",
"adminLevel": "CUSTOMER_ADMIN",
"appRights": ["users.read", "invitations.create"]
}keycloakId est le compte Keycloak de l'utilisateur dans l'environnement de la session : il est égal au sub du jeton, en dev et en staging comme en prod. appRights est lu dans la matrice profils × droits de cet environnement.
Un jeton expiré donne 401 Token expired ; un jeton illisible 401 Invalid token format.
/api/token/check/admin-levelIndique si l'utilisateur a au moins le niveau demandé.
| Champ | Type | Obligatoire | Valeurs |
|---|---|---|---|
token | chaîne | oui | Jeton Keycloak de l'utilisateur |
requiredLevel | chaîne | oui | partner, app, network, customer, user, none |
Réponse 200
{
"allowed": true,
"currentLevel": "customer",
"requiredLevel": "customer",
"hierarchy": { "current": 4, "required": 4 }
}Plus le nombre de hierarchy est petit, plus le niveau est élevé.
/api/token/check/teamIndique si l'utilisateur appartient à une équipe, avec un niveau et des droits d'équipe donnés.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
token | chaîne | oui | Jeton Keycloak de l'utilisateur |
teamWid | chaîne | oui | Identifiant court de l'équipe |
requiredLevel | chaîne | non | Niveau minimal, en chiffre : 1 ADMIN, 2 MANAGER, 3 MEMBER, 4 CONTRIBUTOR, 5 VIEWER |
requiredRights | tableau de chaînes | non | Lettres de droits d'équipe exigées, 26 au plus |
Réponse 200
{
"allowed": true,
"isMember": true,
"teamWid": "EXTEA1",
"teamLevel": "2",
"teamLevelName": "MANAGER",
"requiredLevel": "3",
"customRights": ["A", "B"],
"requiredRights": ["A"],
"matchedRights": ["A"],
"missingRights": [],
"capabilities": ["manage_users", "add_data", "edit_data", "delete_data", "view_data"],
"allTeams": [{ "teamWid": "EXTEA1", "teamLevel": "2", "customRights": ["A", "B"], "rawEntry": "EXTEA12AB" }]
}Si l'utilisateur n'est pas membre de l'équipe, isMember et allowed valent false, et teamLevel et teamLevelName valent null.
/api/token/check/hdsIndique si l'utilisateur porte les rôles HDS demandés, et ce qu'il peut faire sur un dossier patient.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
token | chaîne | oui | Jeton Keycloak de l'utilisateur |
requiredRoles | tableau de chaînes | oui | Rôles exigés, tous requis, 50 au plus : HDS_MEDICAL, HDS_HEALTHCARE… |
patientWid | chaîne | non | Identifiant Keycloak (sub) du patient : la réponse indique dans isOwner si l'utilisateur est ce patient |
contributorWid | chaîne | non | Identifiant Keycloak d'un contributeur : la réponse indique dans isContributor si l'utilisateur est ce contributeur |
Réponse 200
{
"allowed": true,
"hdsRoles": ["HDS_MEDICAL"],
"requiredRoles": ["HDS_MEDICAL"],
"matchedRoles": ["HDS_MEDICAL"],
"missingRoles": [],
"isOwner": false,
"capabilities": ["view_patient_folders", "read_medical_documents"],
"canViewPatientFolders": true,
"canDepositDocuments": false,
"canDeleteDocuments": false
}/api/token/check/rolesIndique si l'utilisateur porte des rôles issus de ses profils.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
token | chaîne | oui | Jeton Keycloak de l'utilisateur |
requiredRoles | tableau de chaînes | oui | Codes de rôle, 50 au plus |
mode | chaîne | non | any (au moins un, par défaut) ou all (tous) |
Réponse 200 : { "allowed", "mode", "userRoles", "requiredRoles", "matchedRoles", "missingRoles" }.
/api/token/authorizeCombine plusieurs contrôles en un appel. allowed vaut true si tous les contrôles demandés réussissent.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
token | chaîne | oui | Jeton Keycloak de l'utilisateur |
checks.adminLevel | chaîne | non | Niveau minimal, mêmes valeurs que requiredLevel |
checks.roles | objet | non | { "required": [...], "mode": "any" | "all" } |
checks.team | objet | non | { "wid": "EXTEA1", "level": "3", "rights": ["A"] } |
checks.hds | objet | non | { "roles": [...], "patientWid": "…" } |
curl -s -X POST https://api.wakastart.app/api/token/authorize \
-H "x-api-key: sk_test_exemple" \
-H 'Content-Type: application/json' \
-d "{
\"token\": \"$USER_TOKEN\",
\"checks\": { \"adminLevel\": \"customer\", \"team\": { \"wid\": \"EXTEA1\", \"level\": \"3\" } }
}"Réponse 200
{
"allowed": false,
"tokenValid": true,
"results": {
"adminLevel": { "checked": true, "allowed": true, "details": { "currentLevel": "customer" } },
"team": { "checked": true, "allowed": false, "details": { "isMember": false, "teamWid": "EXTEA1" } }
},
"user": {
"email": "alice@clinique-exemple.fr",
"keycloakId": "6c1f2a9e-4b1d-4e0b-9a51-2f6c3d7e8a10",
"adminLevel": "CUSTOMER_ADMIN"
},
"failedChecks": ["team"]
}Un jeton invalide ne provoque pas d'erreur : la réponse vaut { "allowed": false, "tokenValid": false, "results": {}, "user": { "email": "unknown" }, "failedChecks": ["token_validation"] }.
Erreurs communes : 403 Niveau d'administration insuffisant… si l'appelant n'est pas Administrateur client ; 400 si token dépasse 10 000 caractères ou si un champ est inconnu.