# Agir sur Wakastart pour un client

> Déclencher une action Wakastart, comme une invitation, depuis l'appel d'un client de votre wakapp, avec la clé sk_ et le jeton de contexte.

Quand l'appel d'un client de votre wakapp doit déclencher une action Wakastart, votre wakapp la fait avec sa clé `sk_` et y joint un [jeton de contexte](/v1.0/cles-api/jeton-de-contexte). Ce guide prend l'exemple d'une invitation, déclenchée soit par la clé `wsk_` d'un organisme, soit par le bouton « Inviter » d'un utilisateur de votre wakapp.

:::important
Le jeton de contexte est en cours de déploiement. Tant que l'introspection ne renvoie pas de `context_token` sur votre environnement, appelez Wakastart avec votre seule clé `sk_` ; toutes les actions démarrent en mode `observe`.
:::

## Avant de commencer

- Votre wakapp vérifie déjà les clés de ses clients (voir [Vérifier une clé de votre wakapp](/v1.0/cles-api/verifier-une-cle-de-votre-wakapp)).
- Sa clé `sk_` porte le droit Wakastart de l'action, ici `invitations.create`, avec le niveau Administrateur client.
- Vous tenez dans la configuration de votre wakapp la **liste des profils qu'une invitation peut attribuer**, par leur WID.

## Vérifier le droit dans votre wakapp

Avant d'agir sur Wakastart au nom d'un client ou d'un utilisateur, votre wakapp vérifie elle-même, avec son propre mécanisme d'autorisation, qu'il a le droit de le faire chez elle. Wakastart ne peut pas le faire à votre place : `user-context` vérifie seulement que l'utilisateur est actif et a accès à l'application, et le contexte borne l'**organisme**, pas le **droit**.

1. Pour un contexte « clé client », exigez le droit sur la clé, par exemple `RequireAppKey("participants.invite")`.
2. Pour un contexte « utilisateur », exigez le droit dans votre propre modèle d'autorisation.
3. Contrôlez le profil attribué par l'invitation : Wakastart vérifie seulement qu'il appartient à l'organisme. Refusez une invitation sans profil ou dont le profil n'est pas dans votre liste, et refusez **toute** invitation si la liste est vide : par défaut, on n'invite pas.

## Obtenir le contexte

::::tabs{sync="contexte"}
:::tab{label="Clé client"}
Le contexte est renvoyé par l'introspection de la clé `wsk_`, dans le champ `context_token`. Aucun appel supplémentaire n'est nécessaire. L'organisme qu'il porte vient toujours de l'enregistrement de la clé.
:::
:::tab{label="Utilisateur"}
Demandez un contexte avec le jeton d'accès de l'utilisateur, émis pour votre wakapp :

```bash
curl -s -X POST "https://api.wakastart.app/api/app-keys/user-context" \
  -H "x-api-key: sk_test_exemple" \
  -H "Content-Type: application/json" \
  -d '{ "userToken": "'"$USER_ACCESS_TOKEN"'" }'
```

Réponse attendue (`200`) :

```json
{ "context_token": "eyJhbGciOiJFZERTQSJ9.exemple", "exp": 1798790460 }
```

`exp` est l'expiration du contexte, en secondes depuis l'epoch : 60 secondes au plus après son émission. Un jeton émis pour une autre application est refusé (`403 AZP_MISMATCH`), un jeton d'un autre environnement que votre clé aussi (`403 USER_TOKEN_ENV_MISMATCH`).
:::
::::

## Présenter le contexte

Joignez le jeton dans l'en-tête `X-WakaStart-Context`, en plus de votre clé `sk_`, et prenez l'organisme cible dans la réponse d'introspection (`customer.wid`) ou dans le compte de l'utilisateur, jamais dans la requête du client :

```bash
curl -s -X POST "https://api.wakastart.app/api/invitations" \
  -H "x-api-key: sk_test_exemple" \
  -H "X-WakaStart-Context: $CONTEXT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "customerId": "ALPHA1", "invitedEmail": "alice@exemple.fr", "profileWid": "PRFAP1" }'
```

Respectez ces règles :

- **Durée de vie de 60 secondes.** L'action se fait pendant la requête du client. Ne stockez pas le jeton, ne le réutilisez pas pour une autre requête, ne le placez pas dans une file d'attente.
- **Un contexte par requête.** Deux requêtes simultanées de deux organismes ne doivent jamais échanger leurs contextes : rangez-le dans un stockage par requête (`AsyncLocalStorage` en Node.js), jamais dans une variable globale.
- **Chaque objet de la demande appartient à l'organisme du contexte** : l'organisme cible, le profil attribué, les équipes, l'invitation ou l'utilisateur visé.
- **Aucun niveau d'administration au-delà d'Administrateur client** pour un compte créé ou modifié sous contexte.

### N'envoyez jamais `Authorization` avec votre clé `sk_`

Quand une requête porte un en-tête `Authorization: Bearer`, Wakastart utilise ce jeton et **ignore** la clé `sk_` : votre contexte ne borne alors plus rien de ce que vous croyez.

- Pour agir avec votre clé : `x-api-key: sk_…` et `X-WakaStart-Context`, rien dans `Authorization`.
- Pour agir avec l'identité de l'utilisateur : son jeton dans `Authorization: Bearer`, sans compter sur la clé.
- Ne mettez pas votre clé `sk_` dans `Authorization` : ce n'est pas un jeton, la requête est refusée.
- Un jeton de contexte n'est jamais un jeton de connexion : présenté dans `Authorization` ou dans `x-enriched-token`, il est refusé.

Votre client vous envoie sa clé dans `Authorization: Bearer wsk_…` ; vous appelez Wakastart avec `x-api-key: sk_…`. Ne relayez jamais l'en-tête `Authorization` reçu du client vers Wakastart.

## Avec le kit

Dans une route protégée par `RequireAppKey` ou `requireAppKey`, `wakastartFetch` envoie votre clé `sk_` en `x-api-key` et le contexte de la requête en cours dans `X-WakaStart-Context` :

```ts
import { wakastartFetch } from "@wakastellar/wakastart-keys";

// Dans une route protégée par RequireAppKey("participants.invite")
const res = await wakastartFetch("/api/invitations", {
  method: "POST",
  json: { customerId: key.customer.wid, invitedEmail, profileWid },
});
```

Pour un contexte « utilisateur », après avoir vérifié son droit dans votre wakapp :

```ts
import { runWithUserContext, wakastartFetch } from "@wakastellar/wakastart-keys";

async function invite(me: CurrentUser, dto: InviteDto) {
  // 1. Contrôle local, avant tout appel à Wakastart
  if (!myAuthorization.can(me, "participants.invite") || !INVITABLE_PROFILE_WIDS.includes(dto.profileWid)) {
    throw new ForbiddenError();
  }
  // 2. L'organisme vient du compte de l'utilisateur, jamais du corps de la requête
  return runWithUserContext(me.accessToken, () =>
    wakastartFetch("/api/invitations", {
      method: "POST",
      json: { customerId: me.customer.wid, invitedEmail: dto.email, profileWid: dto.profileWid },
    }),
  );
}
```

- `wakastartFetch` refuse un en-tête `Authorization` passé par l'appelant et n'accepte qu'un chemin relatif à `WAKASTART_API_URL` : votre clé ne part que vers Wakastart.
- `requireContext: true` refuse l'appel s'il n'y a pas de contexte.
- Passé 60 secondes, `wakastartFetch` lève `WakaStartContextError` au lieu d'appeler Wakastart, quel que soit le mode de l'action (option `onExpiredContext: 'throw'`, par défaut). Avec `onExpiredContext: 'omit'`, il appelle Wakastart sans contexte : accepté en `observe` ou `preferred`, refusé en `required` ou `bound`. Réservez `'omit'` à un traitement long qui ne peut pas se découper.
- `userContext(userToken)` renvoie `{ context_token, exp }` ; `runWithContext(ctx, fn)` permet de gérer le contexte vous-même.
- En mode `bound`, le kit joint le même contexte à chaque appel de la requête : pour une seconde action, obtenez un nouveau contexte.

Le kit réduit les erreurs, il n'est pas une frontière de sécurité : la frontière est la vérification faite par Wakastart.

## Vérifier le résultat

- L'invitation est créée (`201`) dans l'organisme de la clé ou de l'utilisateur.
- Le même appel avec un `customerId` d'un autre organisme est refusé avec `403 CONTEXT_CUSTOMER_MISMATCH` dès que l'action est en `preferred` ou plus strict ; en `observe`, il est accepté et l'écart est journalisé par Wakastart.
- Une erreur `401 CONTEXT_INVALID` indique un contexte expiré ou émis pour une autre application ou un autre environnement.

## Voir aussi

- [Jeton de contexte](/v1.0/cles-api/jeton-de-contexte)
- [Référence API : Invitations](/v1.0/reference-api/invitations)
- [Codes d'erreur du jeton de contexte](/v1.0/codes-d-erreur#jeton-de-contexte)
