Aller au contenu

Guide

Créer une clé API

Automatisations et intégrations · 7 min de lecture

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, remplacez 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

  1. Accédez à Admin → Paramètres → Intégrations et ouvrez l'onglet Accès API.
  2. Cliquez sur Générer une nouvelle clé.
  3. Saisissez un Nom de la clé qui indique son usage, par exemple l'outil qui va l'utiliser et ce qu'il fait. Les rappels d'expiration mentionnent le nom de la clé : un nom clair vous indique donc de quelle intégration il s'agit.
  4. Facultatif : activez Contenu public uniquement, par exemple si vous confiez la clé à un tiers pour afficher du contenu public. Consultez Limiter une clé au contenu public ci-dessous.
  5. Sous Portées & Permissions, cochez uniquement les permissions dont l'intégration a besoin. Consultez la section suivante.
  6. Sous Expiration, conservez Aucune expiration ou choisissez 30 jours, 90 jours, 180 jours ou 365 jours. Le formulaire affiche la date et l'heure exactes auxquelles la clé cessera de fonctionner.
  7. 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.
  8. Cliquez sur Générer une nouvelle clé.
  9. 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, créez une clé de remplacement et révoquez l'ancienne.

Vous ne pouvez pas modifier les permissions, l'expiration ni le réglage Contenu public uniquement d'une clé après sa création. Pour les modifier, créez une clé de remplacement (voir ci-dessous).

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

Les permissions sont présentées sur une ligne par type de données, avec une case pour chaque action. Chaque case correspond à une portée :

Ligne Case Ce qu'elle autorise
Communauté Lire Lire le profil, les paramètres et les métadonnées de la communauté
Contenu Lire Lire les publications, les fils, les réponses et les résultats de recherche
Contenu Écrire Créer, modifier et supprimer des publications et des réponses
Médias Lire Lire les URL signées des médias existants
Médias Envoyer Demander des jetons de téléversement ; couvre aussi la lecture des URL signées des médias
Espaces Lire Lister les espaces et lire le détail des espaces
Membres Lire Rechercher des membres et lire leur profil de base, y compris leurs groupes d'accès
Membres Inviter Inviter des personnes par e-mail ou par un lien d'invitation

La case Lire de la ligne Communauté est cochée à l'ouverture du formulaire. Cocher Écrire ou Envoyer ne coche pas Lire pour vous : un outil qui ne fait que créer des publications n'a besoin que de la case Écrire de la ligne Contenu.

La ligne Membres figure sous Accès sensible. Lire permet à l'intégration de vérifier si une adresse e-mail appartient à votre communauté. Avec Inviter, 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 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.

Limiter une clé au contenu public

Lorsque Contenu public uniquement est activé, une clé ne voit que ce que voit un visiteur non connecté. Cela inclut le nom et la description des espaces privés, mais pas ceux des espaces secrets. Utilisez cette option pour une clé confiée à un tiers ou pour un outil qui n'affiche que du contenu public.

Sans cette option, une clé peut lire en tant que n'importe quel membre désigné par l'intégration, y compris un administrateur, ce qui donne accès aux espaces privés et payants. C'est aussi le cas d'une clé dont seules les cases Lire sont cochées : lecture seule ne veut donc pas dire contenu public uniquement.

Une telle clé ne peut avoir que Lire sur Communauté, Contenu et Espaces. L'activation de l'option décoche et désactive les autres cases. Les requêtes qui désignent un membre sont refusées. Dans la liste Clés API, la clé affiche le libellé Public uniquement. Vos clés existantes ne sont pas concernées.

Quand une clé API expire

Une clé dotée d'une expiration cesse de fonctionner à la date et à l'heure affichées lors de sa création. Les requêtes qui l'utilisent encore sont refusées avec une erreur qui indique à votre développeur que la clé a expiré, et non qu'elle a été révoquée ou mal saisie.

Dans la liste Clés API, la colonne Statut affiche un compte à rebours : Expire dans 62 jours, puis en heures le dernier jour. Le compte à rebours passe dans une couleur d'avertissement lorsqu'il reste 14 jours ou moins. Survolez-le pour voir la date et l'heure exactes. Une fois la clé expirée, son statut indique Expirée.

Les propriétaires et les administrateurs reçoivent un rappel 14 jours avant l'expiration d'une clé, 1 jour avant, puis au moment où elle expire. Chaque rappel est une notification accompagnée d'un e-mail, et indique quand la clé a été utilisée pour la dernière fois : vous pouvez ainsi savoir si quelque chose en dépend encore. Cliquez sur la notification pour ouvrir Accès API avec la clé mise en évidence. Dans l'application Mateflow, la notification affiche les mêmes informations mais n'ouvre rien. L'e-mail est envoyé immédiatement, même si Notifications par e-mail est désactivé dans vos paramètres de notification ou si vos e-mails arrivent sous forme de résumé Quotidien ou Hebdomadaire. Seuls deux réglages vous privent de l'e-mail : avoir désactivé l'e-mail pour Avis système, ou avoir réglé Récapitulatif des notifications (anciennement appelé Fréquence du résumé) sur Désactivé. Les clés révoquées ne font l'objet d'aucun rappel.

Une expiration ne peut pas être prolongée. Pour qu'une intégration continue de fonctionner, remplacez la clé avant son expiration.

Remplacer une clé API

Le remplacement vous donne une nouvelle clé avec les mêmes paramètres, pour que vous puissiez basculer sans interruption : vous pouvez avoir plusieurs clés à la fois. C'est aussi le moyen d'ajouter une expiration à une clé qui n'en a pas.

  1. Dans l'onglet Accès API, ouvrez le menu d'actions de la clé et cliquez sur Créer un remplacement. Lorsqu'il reste 14 jours ou moins à une clé, ou qu'elle a expiré, sa ligne affiche aussi un bouton Remplacer.
  2. Créer une clé de remplacement s'ouvre avec le nom, les permissions, le réglage Contenu public uniquement, la liste blanche IP et l'expiration de l'ancienne clé déjà renseignés. Modifiez ce qu'il faut, puis cliquez sur Générer une nouvelle clé. Si l'ancienne clé possède une permission que ce formulaire ne peut pas accorder, une note « Non copié » la mentionne, et la nouvelle clé ne l'aura pas.
  3. Copiez la nouvelle clé et ajoutez-la à votre intégration.
  4. Une fois que l'intégration utilise la nouvelle clé et qu'une heure apparaît dans Dernière utilisation, cliquez sur Révoquer l'ancienne clé sous Ensuite : retirez l'ancienne clé et confirmez, ou révoquez l'ancienne clé plus tard depuis la liste. Tant que vous ne l'avez pas fait, l'ancienne clé continue de déclencher des rappels d'expiration.

Les deux clés portent le même nom. Distinguez-les grâce au préfixe de la clé affiché sous le nom et à la date de la colonne Créé le.

Révoquer une clé API

  1. Dans l'onglet Accès API, repérez la clé sous Clés API.
  2. Ouvrez son menu d'actions et cliquez sur Révoquer la clé.
  3. 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. La création et la révocation des clés sont enregistrées dans Admin → Paramètres → Journal d’audit, sous Intégrations.

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.
  • Activez Contenu public uniquement pour une clé qui n'affiche que du contenu public, surtout si vous la confiez à un tiers.
  • Définissez une expiration et remplacez les clés à intervalles réguliers : une clé qui fuite à votre insu cessera ainsi de fonctionner d'elle-même.
  • 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 ?

Retour aux guides

Vous ne trouvez pas ce qu'il vous faut ?

Si vous êtes membre d'une communauté, ses administrateurs sont les mieux placés pour vous aider. Si vous créez ou gérez une communauté sur Mateflow, notre équipe peut vous aider.