Aller au contenu

Gérer les clés de votre wakapp dans la console

Créer, modifier, faire tourner et révoquer depuis la console les clés qu'un organisme client utilise pour appeler l'API d'une application.

GuideAdministrateurDéveloppeurBêta
Durée
10 min
Voir en Markdown

L'onglet Clés API de l'app de la console permet de créer et de suivre les clés qu'un organisme client utilise pour appeler l'API d'une application hébergée sur Wakastart. Ce guide couvre la création d'une clé, la modification de ses droits, la rotation de son secret et sa révocation.

Important

Les clés API des wakapps sont en cours de déploiement : l'onglet Clés API de l'app n'apparaît pas encore dans la console. Ce guide décrit le fonctionnement prévu.

Avant de commencer

  • Pour une clé liée à un utilisateur : vous avez accès à l'application dans l'environnement visé.
  • Pour une clé technique : vous êtes administrateur de l'organisme (niveau Administrateur client ou plus).
  • L'application est activée pour l'organisme, et son catalogue de droits contient les droits à accorder (voir Définir les droits de votre application).

Ouvrir l'onglet

L'onglet est accessible par deux chemins :

  • Par application : dans Applications, cliquez sur l'icône Configuration en face de l'application, puis ouvrez l'onglet Clés API de l'app. L'onglet n'existe que pour les applications de type Application.
  • Par client : dans Organisation puis Clients, cliquez sur l'icône engrenage en face du client, puis ouvrez l'onglet Clés API de l'app.

Vous y voyez vos propres clés liées et, si vous êtes administrateur de l'organisme, toutes les clés des organismes de votre portée.

Lire la liste

Pour chaque clé, la liste affiche son nom, son type, l'Utilisateur (clé liée) ou Créée par (clé technique, « (supprimé) » si le compte n'existe plus), ses Droits, son Expiration, son Dernier usage et son statut :

StatutSignification
ActiveLa clé est acceptée par l'application.
SuspendueClé liée dont l'utilisateur est désactivé ; elle reprend à sa réactivation.
ExpiréeL'échéance est passée.
RévoquéeDéfinitivement refusée.

Le badge Droits inopérants signale des droits inscrits sur la clé mais sans effet : l'utilisateur de la clé ne les détient plus, ou ils ne sont plus disponibles dans l'environnement de la clé.

Créer une clé

Ouvrir le formulaire

Cliquez sur Nouvelle clé. La fenêtre Nouvelle clé API de l'app s'ouvre.

Choisir le type

Dans Type de clé, choisissez Liée à un utilisateur (votre compte) ou Technique. Le type technique n'est proposé qu'aux administrateurs de l'organisme.

Renseigner la portée

  • Organisme : pour une clé liée, c'est toujours l'organisme de votre compte ; pour une clé technique, sélectionnez-le.
  • Application et Environnement (Production, Staging ou Dev) : la clé ne sera acceptée que par cette application, dans cet environnement.
  • Nom : un libellé parlant, par exemple « Export compta ».
  • Description (facultative).

Cocher les droits

Dans Droits, cochez les droits à accorder. Seuls sont proposés les droits du catalogue de l'application pour cet environnement que vous détenez vous-même.

Choisir la validité

Dans Validité, choisissez 30 jours, 90 jours, 1 an ou Infinie. Une clé sans date d'expiration reste valide tant qu'elle n'est pas révoquée : réservez ce choix aux intégrations suivies de près.

Créer et copier le secret

Cliquez sur Créer la clé. La fenêtre Clé créée affiche le secret : cliquez sur Copier, transmettez-le de façon sûre à l'équipe qui l'utilisera, puis cliquez sur J'ai copié le secret.

Attention

Le secret ne s'affiche qu'une seule fois. S'il est perdu, faites tourner la clé pour en obtenir un nouveau.

Modifier les droits d'une clé

  1. Cliquez sur Modifier les droits en face de la clé.
  2. Cochez ou décochez les droits, puis cliquez sur Enregistrer.

Vous pouvez toujours retirer un droit, mais vous ne pouvez ajouter que des droits que vous détenez. Un droit que vous ne pouvez plus accorder reste coché : une fois retiré, vous ne pourrez pas le remettre. Le type, l'organisme, l'application et l'environnement d'une clé ne changent jamais : pour en changer, créez une nouvelle clé.

Faire tourner le secret d'une clé

Faites tourner une clé quand son secret est perdu, ou à intervalles réguliers.

  1. Cliquez sur Faire tourner en face de la clé, puis confirmez avec Faire tourner.
  2. Copiez le Nouveau secret avec Copier et transmettez-le à l'équipe qui utilise la clé.

L'ancien secret reste valable 7 jours au plus, jamais au-delà de l'échéance de la clé. 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.

  • Une clé liée ne peut être tournée que par son utilisateur.
  • Une clé technique peut être tournée par un administrateur de l'organisme qui détient lui-même tous les droits de la clé.
  • Si le secret a pu fuiter, révoquez plutôt la clé : la révocation coupe l'accès immédiatement, alors que l'ancien secret d'une clé tournée reste valable jusqu'à 7 jours.

Révoquer une clé

  1. Cliquez sur Révoquer en face de la clé.
  2. Saisissez un Motif (facultatif), par exemple « secret exposé », puis confirmez avec Révoquer.

La révocation est immédiate et définitive : toute intégration qui utilise la clé est refusée dès l'appel suivant. La clé reste dans la liste, au statut Révoquée.

Vérifier le résultat

  • La nouvelle clé apparaît dans la liste au statut Active, avec Jamais utilisée comme dernier usage.
  • Après le premier appel du client à votre wakapp, la colonne Dernier usage se met à jour.
  • Une clé révoquée affiche Révoquée, et un appel avec son secret reçoit un refus de votre wakapp.

Messages fréquents

MessageCe qu'il faut faire
« Vous ne détenez pas ces droits, vous ne pouvez pas les accorder »Retirez les droits cités, ou faites créer la clé par une personne qui les détient
« Vous ne pouvez pas créer ce type de clé. »Une clé technique est réservée aux administrateurs de l'organisme ; une clé liée exige l'accès à l'application dans cet environnement
« Seuls les admins de l'organisme peuvent effectuer cette action. »Vous êtes administrateur, mais pas de cet organisme
« L'application n'est pas activée pour cet organisme. »Activez d'abord l'application pour ce client
« Cette clé est révoquée : elle ne peut plus être modifiée. »Créez une nouvelle clé

Voir aussi