Une clé API permet à votre propre logiciel de communiquer avec votre plateforme via l'API REST, par exemple pour lire les membres, inscrire quelqu'un à un cours ou connecter un site WordPress. Chaque clé est un mot de passe secret destiné à un programme. Vous décidez donc pour chaque clé ce qu'elle peut faire, et vous pouvez la remplacer ou la supprimer à tout moment.
Qui peut gérer les clés API
API se trouve dans le bloc Intégrations et API du menu des paramètres. Votre rôle a besoin de Gérer les clés API en plus de Mettre à jour les paramètres de la plateforme. Cette autorisation n'est jamais disponible pour un rôle personnalisé. Seuls les rôles intégrés Propriétaire et Administrateur peuvent donc travailler ici. La même autorisation ouvre aussi Applications OAuth et Authentification unique.
L'accès à l'API dépend de votre forfait. Si votre forfait ne l'inclut pas, la page affiche « L'accès à l'API est inclus dans toutes les formules payantes. Changez de formule pour créer des clés d'API. » avec Changer de forfait, et Nouvelle clé API reste désactivé. Les clés qui existent déjà sont refusées par l'API jusqu'à ce que le forfait l'inclue de nouveau.
Créer une clé
Cliquez sur Nouvelle clé API. La boîte de dialogue Créer une clé API s'ouvre.
- Saisissez un Nom de la clé qui vous indiquera plus tard qui utilise la clé, par exemple l'outil ou le site web auquel elle appartient. Le nom est obligatoire.
- Décidez ce que la clé peut faire. Une nouvelle clé commence avec un accès complet : toutes les autorisations sont sélectionnées.
- Cliquez sur Créer.
Pour restreindre la clé, cliquez sur Limiter à des autorisations précises. Toutes les autorisations sont décochées, et vous choisissez celles dont vous avez besoin. Les autorisations sont regroupées par domaine, comme Membres, Groupes, Cours ou Paiements, et chaque domaine liste des actions comme Voir ou Gérer avec une courte description. Tout sélectionner et Tout désélectionner basculent tout un domaine d'un coup. Un compteur indique combien d'autorisations la clé possède. Une clé a besoin d'au moins une autorisation, et Réinitialiser à l'accès complet les sélectionne de nouveau toutes.
Après un clic sur Créer, la boîte de dialogue Votre nouvelle clé API affiche la clé complète une seule fois. Copiez-la et conservez-la en lieu sûr. La liste n'affiche ensuite que les quatre derniers caractères, et personne ne peut plus afficher la clé complète.
Utiliser une clé
L'encadré Documentation de l'API au-dessus de la liste affiche l'URL de base de l'API avec un bouton de copie, et Ouvrir la documentation mène à la référence interactive avec tous les endpoints.
Envoyez la clé avec chaque requête, soit comme jeton Bearer dans l'en-tête
Authorization, soit dans l'en-tête X-Api-Key. Les clés commencent par mak_.
Une requête qui exige une autorisation que la clé n'a pas est refusée.
Une clé est liée au membre de l'équipe qui l'a créée. Si cette personne ne fait plus partie de votre espace de travail, la clé cesse de fonctionner. Créez donc les clés des connexions durables avec un compte qui reste.
La liste affiche chaque clé avec Nom, Clé, Dernière utilisation et Créé. Dernière utilisation est mis à jour au plus une fois par minute, ce qui suffit pour voir si une clé est encore utilisée.
Modifier, renouveler et supprimer une clé
Cliquez sur une clé dans la liste, ou utilisez Modifier, l'icône crayon de sa ligne, pour changer son nom ou ses autorisations. Les modifications prennent effet avec Enregistrer.
Si une clé a pu être divulguée, renouvelez-la. Renouveler la clé dans la même boîte de dialogue demande : « Renouveler cette clé ? L'ancien secret cessera immédiatement de fonctionner et les intégrations externes auront besoin du nouveau. » Après votre confirmation, la nouvelle clé apparaît une seule fois dans Votre nouvelle clé API. Le nom et les autorisations restent les mêmes, et Dernière utilisation repart de zéro. Saisissez la nouvelle clé dans chaque outil qui utilisait l'ancienne.
Pour retirer une clé, utilisez Supprimer, l'icône corbeille de sa ligne, ou Supprimer dans la boîte de dialogue ouverte, puis confirmez. Chaque outil qui l'utilise encore est refusé dès lors.
Applications OAuth, authentification unique et webhooks
Coller une clé n'est pas la seule façon de se connecter :
- Applications OAuth permet à d'autres MemberAreas de connecter votre logiciel avec OAuth au lieu d'une clé API collée.
- Authentification unique connecte les membres depuis un autre système. Elle est décrite dans Connexion, inscription et SSO.
- Les webhooks pour les événements des membres et des paiements ont leur propre page sous Paramètres > Webhooks, qui apparaît dès que les paiements sont activés.