Proposer les clés dans votre wakapp
Offrir à vos utilisateurs un écran « Mes clés API » dans votre wakapp : créer, lister, faire tourner et révoquer des clés en leur nom.
- Durée
- 45 min
Votre wakapp peut proposer à ses utilisateurs un écran « Mes clés API », sans les envoyer dans la console Wakastart. Elle appelle alors les opérations de gestion des clés au nom de l'utilisateur connecté, avec son jeton : c'est Wakastart qui applique le plafond de ses droits et sa portée.
Important
Les clés API des wakapps sont en cours de déploiement : les opérations /api/app-keys ne répondent pas encore. Ce guide décrit le fonctionnement prévu.
Avant de commencer
- L'utilisateur est connecté à votre wakapp et vous disposez de son jeton d'accès Keycloak, émis pour votre application (voir Jetons et sessions).
- Ces appels partent de votre serveur ou de votre BFF, avec le jeton de l'utilisateur, jamais avec votre clé
sk_: une clé ne gère jamais de clés, et un appel avec la seule clésk_est refusé (403 API_KEY_CANNOT_MANAGE_KEYS).
Comment Wakastart borne les appels
N'envoyez ni votre application ni votre environnement : Wakastart les déduit du jeton de l'utilisateur. L'application est celle pour laquelle le jeton a été émis, l'environnement celui de la session. Une clé créée depuis votre wakapp vise donc toujours votre application, dans l'environnement où l'utilisateur est connecté, et la liste ne renvoie que les clés de cette application et de cet environnement.
| Situation | Réponse |
|---|---|
appWid ou envType envoyé et différent de ceux du jeton | 403 APP_SCOPE_MISMATCH |
| Le jeton ne désigne aucune application cliente (client inconnu de Wakastart, module, service, application de la plateforme) | 403 APP_NOT_RESOLVED |
| Le jeton a été émis pour une autre application que celle du réseau de l'utilisateur | 403, message Access denied: token authorized party does not match the target application, sans code stable |
| Clé d'une autre application, d'un autre environnement, ou hors de la portée de l'utilisateur | 404, comme une clé inexistante |
Afficher les droits attribuables
Les cases à cocher de votre écran ne doivent proposer que les droits que l'utilisateur peut donner : ceux du catalogue de votre application, disponibles dans l'environnement, qu'il détient lui-même.
curl -s "https://api.wakastart.app/api/app-keys/assignable-rights?type=USER_BOUND" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN"{
"data": [
{ "code": "formations.read", "name": "Lire les formations", "category": "Formations" }
]
}Pour une clé technique, passez type=TECHNICAL et customerWid. Cette liste sert à l'affichage : Wakastart revérifie le plafond à la création.
Créer une clé
curl -s -X POST "https://api.wakastart.app/api/app-keys" \
-H "Authorization: Bearer $USER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "USER_BOUND",
"name": "Export compta",
"description": "Lecture des formations par le SI comptable",
"rights": ["formations.read"],
"validity": "1y"
}'const res = await fetch("https://api.wakastart.app/api/app-keys", {
method: "POST",
headers: { Authorization: `Bearer ${userAccessToken}`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "USER_BOUND", name: "Export compta", rights: ["formations.read"], validity: "1y" }),
});
const created = await res.json();Réponse attendue (201, extrait) :
{
"wid": "K7hq2P",
"name": "Export compta",
"type": "USER_BOUND",
"rights": ["formations.read"],
"status": "ACTIVE",
"expiresAt": "2027-11-02T09:00:00.000Z",
"secret": "wsk_exemple3kTq9"
}Le secret n'est renvoyé qu'une seule fois. Affichez-le à l'utilisateur avec un bouton de copie, puis oubliez-le : ne le stockez pas, ne le journalisez pas.
Pour une clé technique, envoyez "type": "TECHNICAL" et customerWid ; l'utilisateur doit être administrateur de cet organisme.
Lister, modifier, faire tourner et révoquer
| Action | Opération |
|---|---|
| Lister les clés de l'utilisateur | GET /api/app-keys?mine=true, paginée par limit (500 au plus) et offset ; réponse { data, total } |
| Lire une clé | GET /api/app-keys/{wid} |
| Renommer, ajouter ou retirer des droits | PATCH /api/app-keys/{wid} avec { name?, description?, addRights?, removeRights? } |
| Faire tourner le secret | POST /api/app-keys/{wid}/rotate ; nouveau secret renvoyé une seule fois, l'ancien reste valable 7 jours au plus |
| Révoquer | DELETE /api/app-keys/{wid}, corps facultatif { reason }, réponse 204 |
Qui peut faire quoi :
| Action | Qui |
|---|---|
| Créer une clé liée | Tout utilisateur actif qui a accès à l'application dans cet environnement, pour lui-même |
| Créer une clé technique | Les administrateurs de l'organisme |
| Voir, modifier, révoquer | Le propriétaire d'une clé liée ; les administrateurs de l'organisme pour toutes les clés de leur portée |
| Faire tourner | Le propriétaire seul pour une clé liée ; un administrateur de l'organisme pour une clé technique, si les droits de la clé restent sous son propre plafond |
Avec le kit
Le kit @wakastellar/wakastart-keys (voir Vérifier une clé de votre wakapp) enveloppe ces opérations :
import { createKey, listKeys, revokeKey, rotateKey } from "@wakastellar/wakastart-keys";
const user = { token: keycloakAccessToken, enrichedToken }; // ou keycloakAccessToken seul
const created = await createKey(user, {
type: "USER_BOUND",
name: "Export compta",
rights: ["formations.read"],
validity: "1y",
});
// created.secret : à afficher une seule fois, jamais stocké ni journalisé
await listKeys(user, { mine: true });
await rotateKey(user, created.wid); // l'ancien secret reste valable 7 jours au plus
await revokeKey(user, created.wid, "plus utilisée");getKey et updateKey (addRights, removeRights) suivent le même modèle. Une erreur de Wakastart lève WakaStartApiError, avec status, code (par exemple RIGHTS_EXCEED_CEILING) et details.
Vérifier le résultat
- La clé créée apparaît dans
GET /api/app-keys?mine=true, au statutACTIVE, sans secret. - Une introspection de son secret par votre wakapp renvoie
"active": trueavec les droits accordés. - Après
DELETE, la même introspection renvoie{ "active": false }.