Skip to content

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.

ReferenceDeveloper

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

ChampTypeDescription
widchaîneIdentifiant 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
emailchaîneE-mail
firstName, lastNamechaînePrénom et nom, s'ils sont connus
isActivebooléenCompte actif
adminLevelchaîneNiveau d'administration : PARTNER_ADMIN, APP_ADMIN, NETWORK_ADMIN, CUSTOMER_ADMIN, USER ou NONE
hdsRolestableau de chaînesRôles HDS : HDS_ADMIN, HDS_PATIENT, HDS_HEALTHCARE, HDS_STORAGE, HDS_DELETE, HDS_MEDICAL
partnerobjet { wid, name }Propriétaire de l'application
networkobjet { wid, name }Réseau du client
customerobjet { wid, name }Client de l'utilisateur
teamstableauÉquipes : { wid, name, teamLevel }, teamLevel valant ADMIN, MANAGER, MEMBER, CONTRIBUTOR, VIEWER ou NONE
profileobjetProfil de l'utilisateur pour l'environnement de la session : { wid, name, description, rights }
profile.rightstableauDroits applicatifs du profil dans cet environnement : { code, name, description, category }
brandingobjetVisuels 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
lastLoginAtchaîne ISO 8601Dernière connexion
createdAtchaîne ISO 8601Cré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é

GET/api/me

Accè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.

Bash
curl -s https://api.wakastart.app/api/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
TypeScript
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

JSON
{
  "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

StatutMessageCause
401Authentification requise: Bearer token (Authorization header) ou cle API (x-api-key header)Aucune identité valide dans la requête
404Utilisateur non trouvéLe compte Keycloak n'a pas de compte Wakastart associé pour cette application
409Impossible 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

POST/api/auth/enrich

Accè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).

Bash
curl -s -X POST https://api.wakastart.app/api/auth/enrich \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Réponse 200

JSON
{
  "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 :

ChampDescription
sub, emailIdentité Keycloak de l'utilisateur
azpClient Keycloak de l'application
wadlNiveau d'administration
pid, nid, cid, aid, uidIdentifiants courts du propriétaire, du réseau, du client, de l'application et de l'utilisateur
wenvEnvironnement de la session : dev, staging ou prod
given_name, family_namePrénom et nom
expExpiration, 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.

POST/api/token/enrich

Variante 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.

ChampTypeObligatoireContraintes
tokenchaîneouiJeton Keycloak, 10 000 caractères au plus
Bash
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.

POST/api/token/verify

Vérifie la signature et la validité du jeton et renvoie l'identité qu'il porte.

ChampTypeObligatoireContraintes
tokenchaîneoui10 000 caractères au plus
Bash
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

JSON
{
  "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.

POST/api/token/check/admin-level

Indique si l'utilisateur a au moins le niveau demandé.

ChampTypeObligatoireValeurs
tokenchaîneouiJeton Keycloak de l'utilisateur
requiredLevelchaîneouipartner, app, network, customer, user, none

Réponse 200

JSON
{
  "allowed": true,
  "currentLevel": "customer",
  "requiredLevel": "customer",
  "hierarchy": { "current": 4, "required": 4 }
}

Plus le nombre de hierarchy est petit, plus le niveau est élevé.

POST/api/token/check/team

Indique si l'utilisateur appartient à une équipe, avec un niveau et des droits d'équipe donnés.

ChampTypeObligatoireDescription
tokenchaîneouiJeton Keycloak de l'utilisateur
teamWidchaîneouiIdentifiant court de l'équipe
requiredLevelchaînenonNiveau minimal, en chiffre : 1 ADMIN, 2 MANAGER, 3 MEMBER, 4 CONTRIBUTOR, 5 VIEWER
requiredRightstableau de chaînesnonLettres de droits d'équipe exigées, 26 au plus

Réponse 200

JSON
{
  "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.

POST/api/token/check/hds

Indique si l'utilisateur porte les rôles HDS demandés, et ce qu'il peut faire sur un dossier patient.

ChampTypeObligatoireDescription
tokenchaîneouiJeton Keycloak de l'utilisateur
requiredRolestableau de chaînesouiRôles exigés, tous requis, 50 au plus : HDS_MEDICAL, HDS_HEALTHCARE…
patientWidchaînenonIdentifiant Keycloak (sub) du patient : la réponse indique dans isOwner si l'utilisateur est ce patient
contributorWidchaînenonIdentifiant Keycloak d'un contributeur : la réponse indique dans isContributor si l'utilisateur est ce contributeur

Réponse 200

JSON
{
  "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
}
POST/api/token/check/roles

Indique si l'utilisateur porte des rôles issus de ses profils.

ChampTypeObligatoireDescription
tokenchaîneouiJeton Keycloak de l'utilisateur
requiredRolestableau de chaînesouiCodes de rôle, 50 au plus
modechaînenonany (au moins un, par défaut) ou all (tous)

Réponse 200 : { "allowed", "mode", "userRoles", "requiredRoles", "matchedRoles", "missingRoles" }.

POST/api/token/authorize

Combine plusieurs contrôles en un appel. allowed vaut true si tous les contrôles demandés réussissent.

ChampTypeObligatoireDescription
tokenchaîneouiJeton Keycloak de l'utilisateur
checks.adminLevelchaînenonNiveau minimal, mêmes valeurs que requiredLevel
checks.rolesobjetnon{ "required": [...], "mode": "any" | "all" }
checks.teamobjetnon{ "wid": "EXTEA1", "level": "3", "rights": ["A"] }
checks.hdsobjetnon{ "roles": [...], "patientWid": "…" }
Bash
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

JSON
{
  "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.