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.
This page has not been translated yet and is shown in French.
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.