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.
- Durée
- 30 min
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, iciinvitations.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.
- Pour un contexte « clé client », exigez le droit sur la clé, par exemple
RequireAppKey("participants.invite"). - Pour un contexte « utilisateur », exigez le droit dans votre propre modèle d'autorisation.
- 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 :
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) :
{ "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 :
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 (
AsyncLocalStorageen 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_…etX-WakaStart-Context, rien dansAuthorization. - Pour agir avec l'identité de l'utilisateur : son jeton dans
Authorization: Bearer, sans compter sur la clé. - Ne mettez pas votre clé
sk_dansAuthorization: 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
Authorizationou dansx-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 :
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 :
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 },
}),
);
}wakastartFetchrefuse un en-têteAuthorizationpassé par l'appelant et n'accepte qu'un chemin relatif àWAKASTART_API_URL: votre clé ne part que vers Wakastart.requireContext: truerefuse l'appel s'il n'y a pas de contexte.- Passé 60 secondes,
wakastartFetchlèveWakaStartContextErrorau lieu d'appeler Wakastart, quel que soit le mode de l'action (optiononExpiredContext: 'throw', par défaut). AveconExpiredContext: 'omit', il appelle Wakastart sans contexte : accepté enobserveoupreferred, refusé enrequiredoubound. 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
customerIdd'un autre organisme est refusé avec403 CONTEXT_CUSTOMER_MISMATCHdès que l'action est enpreferredou plus strict ; enobserve, il est accepté et l'écart est journalisé par Wakastart. - Une erreur
401 CONTEXT_INVALIDindique un contexte expiré ou émis pour une autre application ou un autre environnement.