Aller au contenu

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.

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

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.

SituationRéponse
appWid ou envType envoyé et différent de ceux du jeton403 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'utilisateur403, 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'utilisateur404, 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.

Bash
curl -s "https://api.wakastart.app/api/app-keys/assignable-rights?type=USER_BOUND" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"
JSON
{
  "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é

Bash
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"
  }'
TypeScript
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) :

JSON
{
  "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

ActionOpération
Lister les clés de l'utilisateurGET /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 droitsPATCH /api/app-keys/{wid} avec { name?, description?, addRights?, removeRights? }
Faire tourner le secretPOST /api/app-keys/{wid}/rotate ; nouveau secret renvoyé une seule fois, l'ancien reste valable 7 jours au plus
RévoquerDELETE /api/app-keys/{wid}, corps facultatif { reason }, réponse 204

Qui peut faire quoi :

ActionQui
Créer une clé liéeTout utilisateur actif qui a accès à l'application dans cet environnement, pour lui-même
Créer une clé techniqueLes administrateurs de l'organisme
Voir, modifier, révoquerLe propriétaire d'une clé liée ; les administrateurs de l'organisme pour toutes les clés de leur portée
Faire tournerLe 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 :

TypeScript
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 statut ACTIVE, sans secret.
  • Une introspection de son secret par votre wakapp renvoie "active": true avec les droits accordés.
  • Après DELETE, la même introspection renvoie { "active": false }.

Voir aussi