Clés API de votre wakapp
Les clés wsk_ qu'un organisme client utilise pour appeler l'API de votre wakapp : types, droits, plafond, validité, rotation et révocation.
This page has not been translated yet and is shown in French.
Les organismes clients de votre wakapp veulent souvent l'appeler depuis leur propre système d'information : lire leurs formations, créer des projets, inviter des participants. Wakastart crée, stocke, vérifie et révoque les clés qu'ils utilisent pour cela ; votre wakapp les applique, en demandant à Wakastart ce que vaut chaque clé reçue, puis en contrôlant ses droits comme pour un utilisateur.
Important
Les clés API des wakapps sont en cours de déploiement et ne sont pas encore disponibles : l'onglet Clés API de l'app n'apparaît pas encore dans la console et les opérations /api/app-keys ne répondent pas encore. Cette page décrit le fonctionnement prévu.
Définition
Une clé de wakapp est l'équivalent d'un utilisateur de votre wakapp : elle porte une liste de droits pris dans le catalogue de droits de votre application, ceux que vous attribuez déjà à vos utilisateurs par les profils (voir Droits et profils). Elle ne donne aucun droit sur Wakastart.
Chaque clé est attachée, définitivement, à :
- un organisme, le client propriétaire : votre wakapp limite toutes ses réponses à cet organisme ;
- une application, la vôtre : une clé présentée à une autre wakapp est refusée ;
- un environnement,
dev,stagingouprod: une clédevprésentée à votre wakapp de production est refusée.
À ne pas confondre avec votre clé sk_
Clé sk_ | Clé de votre wakapp | |
|---|---|---|
| Utilisée par | Le serveur de votre wakapp | Le système d'information d'un organisme client |
| Pour appeler | L'API publique Wakastart | L'API de votre wakapp |
| Commence par | sk_ | wsk_ |
| Où elle se gère | Équipe Wakastart (voir Obtenir une clé API) | Onglet Clés API de l'app de la console, ou depuis votre wakapp |
| Droits | Niveau d'administration et profil Wakastart | Droits du catalogue de votre application |
Une clé wsk_ envoyée directement à l'API publique Wakastart est refusée avec un 401 : elle n'y a aucun droit.
Pourquoi ça existe
Sans ce mécanisme, chaque wakapp devrait inventer ses propres clés, les stocker, les révoquer et les relier à ses utilisateurs. Wakastart connaît déjà les organismes, les utilisateurs et les droits de votre application : il gère le cycle de vie des clés et répond à une seule question de votre wakapp, « que vaut cette clé ? ». La révocation d'une clé ou le départ de son utilisateur prend ainsi effet dès l'appel suivant, sans rien développer de votre côté.
Comment ça marche
Deux types de clés
| Type | Valeur | Qui la crée | Droits à l'usage | Fin de vie |
|---|---|---|---|---|
| Liée à un utilisateur | USER_BOUND | Tout utilisateur qui a accès à l'application dans cet environnement, pour lui-même | Droits de la clé croisés avec les droits actuels de l'utilisateur, recalculés à chaque vérification | Suspendue si le compte est désactivé ; révoquée s'il est supprimé ou perd l'accès à l'application |
| Technique | TECHNICAL | Les administrateurs de l'organisme (niveau Administrateur client ou plus, avec autorité sur cet organisme) | Fixés à la création, puis bornés à chaque vérification par les droits que l'organisme détient encore | Survit au départ de son créateur ; les administrateurs de l'organisme en sont prévenus par e-mail |
L'organisme d'une clé liée est toujours celui du compte de son utilisateur. Le type, l'organisme, l'application et l'environnement d'une clé sont fixés à la création et ne changent jamais.
Le plafond
Personne ne crée ni ne modifie une clé pour lui donner plus de droits qu'il n'en a lui-même. Wakastart le vérifie à la création et à chaque ajout de droits : chaque droit demandé doit figurer parmi les droits actuels de la personne qui agit, pour cette application et cet environnement. Sinon, la demande est refusée avec le code RIGHTS_EXCEED_CEILING et la liste des droits manquants.
- Retirer un droit est toujours permis à qui gère la clé.
- Une clé n'a pas de niveau d'administration, seulement des droits.
- Un droit supprimé de votre catalogue disparaît des clés qui le portaient, comme pour les utilisateurs.
- Sur une clé liée, un droit que l'utilisateur ne détient plus reste inscrit mais n'a aucun effet : il est signalé comme droit inopérant.
Pour un contrôle plus fin, ajoutez des droits à votre catalogue, par exemple formations.read et formations.export : vos utilisateurs peuvent aussi s'en servir. Il n'existe pas de droits par chemin et par verbe HTTP.
Le secret
- Il est affiché une seule fois, à la création ou à la rotation. Wakastart n'en garde qu'une empreinte et ne peut pas le relire.
- Il commence par
wsk_. Ce préfixe sert uniquement à repérer une clé publiée par erreur, dans un dépôt de code ou un ticket. Ne fondez aucune décision sur la forme du secret : seule la réponse de Wakastart fait foi. - Le client l'envoie à votre wakapp dans un en-tête, en HTTPS. Par convention :
Authorization: Bearer <secret>. Jamais dans une URL, jamais dans un journal.
Validité, rotation et révocation
- Validité : 30 jours, 90 jours, 1 an (par défaut) ou infinie. Une clé sans échéance reste valide tant qu'elle n'est pas révoquée : réservez-la aux intégrations suivies de près.
- Rotation : un nouveau secret est émis et affiché une seule fois. L'ancien reste valable 7 jours au plus, jamais au-delà de l'échéance de la clé, le temps que le client bascule. Une nouvelle rotation pendant ce délai coupe immédiatement le secret qui était déjà en sursis : seuls le nouveau secret et le précédent restent valides. Les droits, l'organisme, l'application, l'environnement et l'échéance ne changent pas.
- Révocation : immédiate et définitive. La clé est refusée dès l'appel suivant et reste visible, au statut révoqué, pour l'historique.
L'API ne connaît que trois statuts, ACTIVE, SUSPENDED et REVOKED : une clé dont l'échéance expiresAt est passée est refusée, et la console l'affiche Expirée.
La vérification à chaque appel
À chaque appel d'un client, votre wakapp envoie le secret reçu à Wakastart, avec sa propre clé sk_. Wakastart répond si la clé est active et, si oui, avec son organisme et ses droits effectifs. Votre wakapp ne garde jamais une réponse positive en cache : c'est ce qui rend la révocation immédiate. Le détail est dans Vérifier une clé de votre wakapp.
Exemples
- Un export comptable. Un administrateur de l'Organisme Alpha crée une clé technique portant
formations.read, valable un an. Le SI comptable de l'organisme lit chaque nuit ses formations, et seulement les siennes. - Un script personnel. Une formatrice crée une clé liée à son compte pour automatiser ses inscriptions. Si son compte est désactivé, la clé est suspendue ; si elle perd le droit
participants.invite, la clé le perd aussi. - Un départ. Le créateur d'une clé technique quitte l'organisme : la clé continue de fonctionner, et les administrateurs de l'organisme sont prévenus par e-mail pour décider de la garder ou de la révoquer.