Une clé API permet à un développeur, ou à un outil que vous utilisez, de se servir de l'Open API de Mateflow pour lire et écrire les données de votre communauté. Vous créez et révoquez les clés API dans Admin → Paramètres → Intégrations → Accès API. Chaque clé ne fonctionne que pour une seule communauté.
Qui peut le faire : Les propriétaires et les administrateurs. · Où : Sur le web (console d'administration). · Offre : L'accès à l'API, ainsi que le nombre de requêtes API que votre communauté peut effectuer par jour, dépendent de votre offre de la plateforme.
Les clés API sont propres à chaque communauté
Les clés API appartiennent à une seule communauté, et les requêtes effectuées avec une clé agissent toujours sur cette communauté. Pour connecter plusieurs communautés, créez une clé dans la console d'administration de chacune.
Le tableau de bord créateur (app.mateflow.com) ne propose pas de clés API. Les clés au niveau de l'espace de travail qui s'y trouvaient ont été remplacées par des clés par communauté. La page Aperçu d'une communauté dans le tableau de bord renvoie vers sa page Intégrations.
Créer une clé API
- Accédez à Admin → Paramètres → Intégrations et ouvrez l'onglet Accès API.
- Cliquez sur Générer une nouvelle clé.
- Saisissez un Nom de la clé qui indique son usage, par exemple l'outil qui va l'utiliser.
- Sous Portées & Permissions, cochez uniquement les permissions dont l'intégration a besoin. Consultez la section suivante.
- Facultatif : sous Liste blanche IP (optionnel), saisissez les adresses ou plages d'adresses IP autorisées à utiliser la clé, séparées par des virgules.
- Cliquez sur Générer une nouvelle clé.
- Copiez la clé depuis Clé API générée, conservez-la en lieu sûr, puis cliquez sur Terminé.
Vous ne pouvez voir la clé complète qu'une seule fois. Si vous la perdez, générez une nouvelle clé et révoquez l'ancienne.
Si l'onglet Accès API affiche une invitation à passer à une offre supérieure, votre offre de la plateforme n'inclut pas l'accès à l'API. La carte Point de terminaison API affiche l'URL de base des requêtes et la limite quotidienne de requêtes de votre offre, qui est réinitialisée à 00:00 UTC.
Portées (permissions) des clés API
| Portée | Ce qu'elle autorise |
|---|---|
| Lire la communauté | Lire le profil, les paramètres et les métadonnées de la communauté |
| Lire le contenu | Lire les publications, les fils, les réponses et les résultats de recherche |
| Écrire du contenu | Créer, modifier et supprimer des publications et des réponses |
| Envoyer des médias | Demander des jetons de téléversement ; couvre aussi la lecture des URL signées des médias |
| Lire les médias | Lire les URL signées des médias existants |
| Lire les espaces | Lister les espaces et lire le détail des espaces |
| Lire les membres | Rechercher des membres et lire leur profil de base, y compris leurs groupes d'accès |
| Inviter des membres | Inviter des personnes par e-mail ou par un lien d'invitation |
Lire les membres et Inviter des membres figurent sous Accès sensible. Lire les membres permet à l'intégration de vérifier si une adresse e-mail appartient à votre communauté. Avec Inviter des membres, les invitations sont envoyées au nom du propriétaire de la communauté, sauf si l'intégration indique un autre expéditeur, et les personnes invitées rejoignent toujours la communauté en tant que membres. Les invitations envoyées via l'API peuvent inclure des groupes d'accès. Consultez Comment fonctionnent les groupes d'accès.
Les portées d'une clé ne peuvent pas être modifiées par la suite. Les clés plus anciennes peuvent afficher Toutes (hérité) : elles ne conservent que les portées qui existaient au moment de leur création. Créez une nouvelle clé pour utiliser les portées plus récentes.
Révoquer une clé API
- Dans l'onglet Accès API, repérez la clé sous Clés API.
- Ouvrez son menu d'actions et cliquez sur Révoquer la clé.
- Confirmez. La révocation est irréversible, et tout outil qui utilise la clé cesse de fonctionner.
La liste affiche pour chaque clé son Statut (Active, Expirée ou Révoquée) et sa date de Dernière utilisation. Les requêtes API n'apparaissent pas dans les Journaux de livraison : c'est donc avec Dernière utilisation que vous vérifiez si une clé est encore utilisée. Déconnecter Slack, Discord ou Zapier ne révoque aucune clé API.
Sécuriser vos clés API
- Conservez les clés API sur un serveur, et non dans un site web ou une application que d'autres peuvent télécharger, et envoyez les requêtes en HTTPS.
- Donnez à chaque outil sa propre clé, avec uniquement les portées dont il a besoin, pour pouvoir en révoquer une sans casser les autres.
- Ajoutez une Liste blanche IP lorsque l'outil appelle l'API depuis des adresses fixes.
- Révoquez immédiatement une clé si elle a pu fuiter, puis créez-en une de remplacement.
Où trouver la documentation de l'API
La référence de l'API couvre les points de terminaison, les formats de requête et de réponse, les portées, les codes d'erreur et des exemples de code. Dans l'onglet Accès API, la carte Documentation développeur comporte un bouton Ouvrir la documentation qui mène à mateflow.com/developers. Envoyez ce lien à votre développeur. Il n'a pas besoin de compte dans votre communauté, et la page est accessible même si votre offre n'inclut pas l'accès à l'API.
Articles associés
Ce guide vous a-t-il été utile ?