Aller au contenu

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.

GuideDéveloppeurBêta
Durée
30 min
Voir en Markdown

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

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

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 :

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

TypeScript
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