# Jeton de contexte

> Borner à l'organisme d'un client une action que votre wakapp fait sur Wakastart avec sa clé sk_, et en tracer l'origine.

Une clé de votre wakapp n'a aucun droit sur Wakastart. Quand l'appel d'un client doit déclencher une action Wakastart, inviter un apprenant par exemple, c'est votre wakapp qui la demande, avec sa propre clé `sk_`. Elle y joint un **jeton de contexte**, qui borne l'action à l'organisme du client et en prouve l'origine.

:::important
Le jeton de contexte est en cours de déploiement. Tant que l'introspection ne renvoie pas de `context_token` sur votre environnement, continuez d'appeler Wakastart avec votre seule clé `sk_`. Au lancement, toutes les actions sont en mode `observe` : un appel sans contexte n'est refusé qu'une fois l'action passée en `required` ou `bound` pour votre application.
:::

## Définition

Le jeton de contexte est un jeton signé par Wakastart, valable **60 secondes au plus**. Il atteste que Wakastart a vérifié, il y a moins d'une minute, soit une clé d'un organisme présentée à votre wakapp, soit le jeton d'un utilisateur de votre wakapp. Votre wakapp le joint à ses appels dans l'en-tête `X-WakaStart-Context`, en plus de sa clé `sk_`.

Il ne fait que **restreindre** :

```text
organismes effectifs = organismes de la clé sk_ ∩ organisme(s) du contexte
droits effectifs     ⊆ droits de la clé sk_
```

Il n'ajoute aucun droit à votre clé `sk_` : il borne l'organisme.

## Pourquoi ça existe

La clé `sk_` d'une wakapp couvre souvent plusieurs organismes. Prenons une wakapp de formation dont la clé couvre l'Organisme Alpha et l'Organisme Beta :

1. Le SI de l'Organisme Alpha demande à la wakapp d'inviter un apprenant. La wakapp vérifie la clé `wsk_` reçue : organisme Alpha, droit `participants.invite` présent.
2. La wakapp appelle `POST /api/invitations` avec sa clé `sk_`.

Si la wakapp prend l'organisme cible dans la requête du client, par erreur ou par malveillance, la clé de l'Organisme Alpha fait inviter quelqu'un chez l'Organisme Beta. Sans contexte, Wakastart voit une demande légitime, avec une clé valable sur les deux organismes, et ne sait pas quel client l'a déclenchée. Avec le contexte, Wakastart refuse toute action hors de l'organisme qui a présenté sa clé.

## Comment ça marche

### Deux contextes

| Contexte | Quand | Comment l'obtenir | Organisme imposé |
|---|---|---|---|
| **Clé client** (`origin_type: customer_api_key`) | Un client appelle votre wakapp avec une clé de votre wakapp, avec ou sans personne derrière | Champ `context_token` de la réponse d'introspection | Celui de la clé, toujours lu dans l'enregistrement de la clé |
| **Utilisateur** (`origin_type: user`) | Un utilisateur connecté à votre wakapp y détient le droit, mais pas le droit Wakastart correspondant : le bouton « Inviter » d'un formateur, par exemple | `POST /api/app-keys/user-context` avec le jeton de l'utilisateur | Ceux de sa portée ; un administrateur réseau peut en avoir plusieurs |

Le contexte « utilisateur » ne remplace pas l'envoi du jeton de l'utilisateur. Si vous transmettez directement ce jeton à Wakastart, l'action est faite avec ses droits et sa portée, et votre clé est ignorée. Le contexte « utilisateur » sert à l'autre cas : votre wakapp agit avec sa propre clé pour le compte d'un utilisateur qui n'a pas lui-même le droit Wakastart.

### Modes par action

Wakastart règle l'exigence de contexte **par type d'action et par application** :

| Mode | Contexte absent | Contexte présent mais refusé | Usage unique |
|---|---|---|---|
| `observe` | Accepté | Accepté ; l'écart est journalisé par Wakastart | Non |
| `preferred` | Accepté ; l'absence est journalisée | **Refusé** | Non |
| `required` | Refusé (`403 CONTEXT_REQUIRED`) | Refusé | Non |
| `bound` | Refusé (`403 CONTEXT_REQUIRED`) | Refusé | **Oui** |

- Sans usage unique, un contexte valide sert pendant ses 60 secondes : relecture, pagination, plusieurs actions de la même requête.
- En `bound`, un contexte ne sert qu'à **une seule action, sur une seule cible** : le second usage est refusé (`403 CONTEXT_REPLAYED`). Pour une seconde action, obtenez un nouveau contexte.

Toutes les actions démarrent en `observe`. La bascule vers un mode plus strict se fait application par application et par type d'action, en commençant par les invitations, puis les profils, les droits et les comptes. Les nouvelles wakapps ont vocation à démarrer directement en `required`. Joignez donc le contexte dès maintenant à chaque action déclenchée par un client : en `observe`, il ne gêne pas, et votre wakapp sera prête au passage en `required`.

### Ce que Wakastart vérifie

Avec un contexte, Wakastart refuse notamment :

- une action dont l'organisme cible n'est pas celui du contexte ;
- une demande dont un objet (profil attribué, équipe, invitation, utilisateur visé) n'appartient pas à l'organisme du contexte ;
- la création ou la modification d'un compte avec un niveau d'administration au-dessus d'Administrateur client ;
- un contexte expiré, ou émis pour une autre application ou un autre environnement ;
- un contexte dont la clé client a été révoquée, suspendue, ou dont les droits ont changé depuis son émission.

Par ailleurs, avec ou sans contexte, personne n'attribue un niveau supérieur au sien : votre clé `sk_` a le niveau de son compte. La liste complète des refus est dans [Codes d'erreur](/v1.0/codes-d-erreur#jeton-de-contexte).

### Ce que le contexte garantit, et ce qu'il ne garantit pas

- Il prouve que Wakastart a vérifié, il y a moins de 60 secondes, une clé de cet organisme présentée à votre wakapp, ou le jeton d'un utilisateur de votre wakapp.
- Il empêche votre code de viser un autre organisme : votre wakapp ne peut pas fabriquer un contexte pour un organisme dont aucune clé ne lui a été présentée.
- Il ne prouve **pas** que l'utilisateur a le droit de demander l'action dans votre wakapp, ni que l'opération a été voulue par le client : ce contrôle reste celui de votre wakapp.
- Wakastart trace chaque action faite avec un contexte : votre application, l'origine prouvée (clé client ou utilisateur) et l'organisme réellement touché.

## Exemples

- **Un traitement nocturne.** Le SI de l'Organisme Alpha appelle votre wakapp avec sa clé `wsk_` pour inscrire des apprenants. L'introspection renvoie un `context_token` ; votre wakapp le joint à chaque `POST /api/invitations` de cette requête.
- **Le bouton « Inviter » d'un formateur.** Le formateur détient `participants.invite` dans votre wakapp, mais aucun droit Wakastart. Votre wakapp vérifie son droit, obtient un contexte « utilisateur », puis invite avec sa clé `sk_` dans l'organisme du formateur.

## Pour aller plus loin

- [Agir sur Wakastart pour un client](/v1.0/cles-api/agir-sur-wakastart-pour-un-client)
- [Vérifier une clé de votre wakapp](/v1.0/cles-api/verifier-une-cle-de-votre-wakapp)
- [Référence API : jeton de contexte](/v1.0/reference-api/cles-api#obtenir-un-contexte-utilisateur)
