# 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 | E-mail |
| `firstName`, `lastName` | chaîne | Prénom et nom, s'ils sont connus |
| `isActive` | booléen | Compte actif |
| `adminLevel` | chaîne | [Niveau d'administration](/v1.0/glossaire#niveau-dadministration) : `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é

::endpoint{method="GET" path="/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"
```

```ts
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**

| 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

::endpoint{method="POST" path="/api/auth/enrich"}

**Accès** : public ; le jeton Keycloak envoyé dans `Authorization` fait office de preuve.

Renvoie un [jeton enrichi](/v1.0/glossaire#jeton-enrichi) signé par Wakastart, à envoyer ensuite dans l'en-tête `x-enriched-token` (voir [Authentification](/v1.0/reference-api/authentification-api#jeton-enrichi)).

```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 :

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

::endpoint{method="POST" path="/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.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `token` | chaîne | oui | Jeton 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](/v1.0/reference-api/cles-api).

**Accès commun** : appelant de niveau Administrateur client (`CUSTOMER_ADMIN`) au minimum.

::endpoint{method="POST" path="/api/token/verify"}

Vé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 |

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

::endpoint{method="POST" path="/api/token/check/admin-level"}

Indique 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`**

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

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

::endpoint{method="POST" path="/api/token/check/team"}

Indique si l'utilisateur appartient à une [équipe](/v1.0/glossaire#é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`**

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

::endpoint{method="POST" path="/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.

| 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`**

```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
}
```

::endpoint{method="POST" path="/api/token/check/roles"}

Indique 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" }`.

::endpoint{method="POST" path="/api/token/authorize"}

Combine 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": "…" }` |

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