Aller au contenu

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.

ConceptDéveloppeurAdministrateurBêta
Voir en Markdown

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, staging ou prod : une clé dev présentée à votre wakapp de production est refusée.

À ne pas confondre avec votre clé sk_

Clé sk_Clé de votre wakapp
Utilisée parLe serveur de votre wakappLe système d'information d'un organisme client
Pour appelerL'API publique WakastartL'API de votre wakapp
Commence parsk_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
DroitsNiveau d'administration et profil WakastartDroits 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

TypeValeurQui la créeDroits à l'usageFin de vie
Liée à un utilisateurUSER_BOUNDTout utilisateur qui a accès à l'application dans cet environnement, pour lui-mêmeDroits de la clé croisés avec les droits actuels de l'utilisateur, recalculés à chaque vérificationSuspendue si le compte est désactivé ; révoquée s'il est supprimé ou perd l'accès à l'application
TechniqueTECHNICALLes 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 encoreSurvit 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.
Chargement du schéma…

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.

Pour aller plus loin