# Jeton enrichi et /me

> Jeton Keycloak, jeton enrichi et GET /api/me : ce que porte chacun, comment les obtenir et lequel utiliser pour quoi.

Après la connexion, votre application dispose d'un jeton Keycloak. Wakastart en tire deux choses : un **[jeton enrichi](/v1.0/glossaire#jeton-enrichi)**, court et signé, qui dit qui est l'utilisateur et dans quelle organisation ; et la réponse de **`GET /api/me`**, complète, qui ajoute son profil, ses droits, ses équipes et l'habillage à appliquer.

## Définition

```mermaid
flowchart LR
  K["Jeton Keycloak<br/>émis par l'instance de l'environnement<br/>azp = WID de l'application"]
  K -->|"POST /api/auth/enrich"| W["Jeton enrichi<br/>niveau, organisation, environnement<br/>signé par Wakastart"]
  K -->|"Authorization: Bearer"| ME["GET /api/me<br/>profil, droits, équipes, habillage"]
  W -->|"x-enriched-token"| ME
```

| | Jeton Keycloak | Jeton enrichi | Réponse de `/api/me` |
|---|---|---|---|
| **Émis par** | l'instance Keycloak de l'environnement | Wakastart | l'API publique |
| **Contient** | identité OIDC, realm (dans l'émetteur), application (`azp`) | niveau d'administration, WID du partenaire, du réseau, du client, de l'application et de l'utilisateur, environnement, thème, langue | identité, organisation, profil de l'environnement avec ses droits, équipes, habillage |
| **Contient les droits ?** | non | non | oui |
| **Durée** | réglée par le realm | celle du jeton Keycloak, sinon 15 minutes | lue à chaque appel |
| **Usage** | s'authentifier auprès de l'API publique | s'authentifier ; son `payload`, lu à l'émission, donne l'organisation sans autre appel | décider de ce que l'utilisateur peut faire, habiller l'interface |

## Pourquoi ça existe

Le jeton Keycloak ne connaît que l'identité : il ignore le client de l'utilisateur, son profil et ses droits, qui vivent dans Wakastart. Le jeton enrichi ajoute ce contexte tout en restant assez petit pour voyager dans un cookie ; c'est pourquoi il ne transporte pas les droits, trop nombreux. `GET /api/me` donne tout, au prix d'un appel.

## Comment ça marche

### Le jeton enrichi

`POST https://api.wakastart.app/api/auth/enrich`, avec le jeton Keycloak en `Authorization: Bearer`, renvoie `{ token, payload }` : le jeton signé et son contenu décodé. Ses clés de vérification ne sont pas publiées : lisez le contenu dans `payload`, au moment de l'émission, et faites vérifier le jeton par l'API publique plutôt que de décoder un jeton reçu d'ailleurs. Ses revendications :

| Revendication | Contenu |
|---|---|
| `sub`, `email`, `given_name`, `family_name` | identité de l'utilisateur |
| `azp` | l'application pour laquelle le jeton Keycloak a été émis |
| `wadl` | niveau d'administration |
| `pid`, `nid`, `cid`, `aid`, `uid` | WID du partenaire, du réseau, du client, de l'application et de l'utilisateur |
| `wenv` | environnement de connexion : `dev`, `staging` ou `prod`. C'est lui qui désigne la fiche de l'utilisateur et la matrice de droits utilisées par toute l'API |
| `wthm`, `wlng` | thème et langue, résolus en cascade |
| `jti`, `exp`, `iss` | identifiant unique, expiration, émetteur `wakastart-token-service` |

L'enrichissement échoue si l'utilisateur n'a pas de fiche ni d'accès à l'application dans cet environnement, ou si sa fiche est désactivée. Le `uid` est le WID de la fiche de cet environnement : une personne présente sur plusieurs environnements a un WID par environnement.

### `GET /api/me`

`GET https://api.wakastart.app/api/me` accepte le jeton Keycloak (`Authorization: Bearer`) ou le jeton enrichi (`x-enriched-token`). Il renvoie :

- l'identité de la fiche de l'environnement de connexion : `wid`, `email`, `firstName`, `lastName`, `isActive`, `adminLevel`, `hdsRoles`. `/api/me` ne prend aucun paramètre d'environnement : il n'existe pas de lecture « tous environnements » ;
- l'organisation : `partner`, `network`, `customer`, chacun avec son `wid` et son `name` ;
- `teams` : les équipes et le rôle (`teamLevel`) de l'utilisateur dans chacune ;
- `profile` : le profil de cette fiche, avec `rights`, la liste des droits (`code`, `name`, `category`) lus dans la matrice de l'environnement de connexion ;
- `branding` : logos, couleurs et variables CSS du thème, résolus du client vers l'application ;
- `lastLoginAt`, `createdAt`.

```json
{
  "wid": "EXUSR1",
  "email": "claire.martin@exemple.fr",
  "adminLevel": "NONE",
  "customer": { "wid": "EXCLI1", "name": "Clinique Exemple" },
  "teams": [{ "wid": "EXTEA1", "name": "Cardiologie", "teamLevel": "MEMBER" }],
  "profile": {
    "wid": "EXPRF1",
    "name": "Soignant",
    "rights": [{ "code": "dossiers.read", "name": "Lire les dossiers", "category": "Dossiers" }]
  }
}
```

### Ce que l'API vérifie

Quel que soit le jeton présenté, l'API publique vérifie qu'il a été émis **pour l'application** concernée. Elle refuse avec `401` une requête sans jeton valide, et avec `403` un jeton d'une autre application ou un droit manquant. Un changement de profil ou de droits est pris en compte dans la minute.

## Exemples

**Afficher ou masquer un bouton.** Au chargement, le back appelle `/api/me` et transmet au front la liste des codes de `profile.rights`. Le bouton « Signer l'ordonnance » n'apparaît que si `ordonnances.sign` y figure ; l'API de votre application refait la vérification côté serveur.

**Router par organisation sans appel réseau.** Après la connexion, votre serveur garde dans la session le `payload` renvoyé par `POST /api/auth/enrich` et y lit `cid` pour diriger chaque requête vers la base du bon client.

## Lequel utiliser ?

| Vous voulez | Utilisez |
|---|---|
| Appeler l'API publique au nom de l'utilisateur | le jeton Keycloak, ou le jeton enrichi |
| Connaître le client ou l'environnement de l'utilisateur sans appel | le `payload` du jeton enrichi, gardé en session |
| Savoir si l'utilisateur a un droit | `GET /api/me` |
| Habiller l'interface aux couleurs du client | `GET /api/me` (`branding`) |
| Appeler l'API depuis un serveur, sans utilisateur | une [clé API](/v1.0/cles-api) |

## Pour aller plus loin

- [Référence API : jeton et /me](/v1.0/reference-api/jeton-et-me) : les endpoints et tous les champs.
- [Droits, profils et équipes](/v1.0/concepts/droits-profils-et-equipes) : d'où viennent les droits.
- [Connecter vos utilisateurs](/v1.0/demarrer/connecter-vos-utilisateurs) : obtenir le jeton Keycloak et appeler `/api/me`.
- [Authentification de l'API](/v1.0/reference-api/authentification-api) : les trois façons de s'authentifier.
