Les clés d’API sont générées à partir de la page Admin / API. Allez dans Admin-Avancé-Clés d’API :
Après avoir cliqué sur le bouton « Nouvelle clé d’API », vous serez redirigé vers une page pour configurer la clé :
Chaque clé d’API nécessite une description, un niveau d’utilisateur et une portée (scope).
Description
La description peut être tout ce que vous choisissez.
Niveau d’utilisateur
Le menu déroulant Niveau d’utilisateur vous permet de sélectionner soit « Tous les utilisateurs », soit « Utilisateur unique ». Si « Tous les utilisateurs » est sélectionné, la clé peut être utilisée au nom de n’importe quel utilisateur. Ceci est réalisé en définissant l’utilisateur pour lequel vous effectuez la requête comme étant l’Api-Username dans les en-têtes de la requête. (Voir l’exemple d’authentification dans la documentation de l’API pour plus de détails sur la façon de définir les en-têtes de requête.)
Si « Utilisateur unique » est sélectionné, un champ utilisateur apparaîtra sur le formulaire. Entrez le nom d’utilisateur pour lequel vous générez la clé d’API dans ce champ :
Portée (Scope)
Le menu déroulant Portée vous permet de sélectionner soit « Granulaire », « Lecture seule » (Read-only), soit « Global » comme portée.
Si « Lecture seule » est sélectionné comme portée, la clé d’API ne pourra être utilisée que pour effectuer des requêtes GET. La clé pourra effectuer toutes les requêtes GET que l’utilisateur pour lequel la clé a été générée, ou le nom d’utilisateur saisi comme Api-Username de la requête, a l’autorisation d’effectuer.
Si « Global » est sélectionné comme portée, la clé peut être utilisée pour toutes les requêtes que l’utilisateur pour lequel la clé a été générée, ou le nom d’utilisateur saisi comme Api-Username de la requête, a l’autorisation d’effectuer.
Si « Granulaire » est sélectionné comme portée, un formulaire vous permettant de sélectionner parmi les portées disponibles s’ouvrira. Survolez l’icône du point d’interrogation d’une portée pour voir une description de celle-ci. Cliquez sur l’icône de lien de la portée pour voir une liste des chemins et des méthodes de requête que la portée prend en charge. Notez que beaucoup de portées vous permettent d’entrer un paramètre supplémentaire pour limiter les chemins sur le site auxquels la portée autorisera l’accès :
Après avoir configuré la clé d’API et cliqué sur le bouton Enregistrer, la clé d’API complète vous sera affichée une seule fois. Assurez-vous de copier la clé car il n’y a aucun moyen de revoir la clé complète.
Les portées d’API dans Discourse ne peuvent que restreindre les actions qu’une clé d’API peut effectuer par rapport aux permissions existantes de l’utilisateur. Elles ne peuvent pas accorder de permissions supplémentaires au-delà de ce que l’utilisateur associé possède déjà.
Lecture supplémentaire
Détails sur les limites de débit que Discourse applique aux clés d’API : Limites de débit globales et étranglement (throttling) dans Discourse.
Documentation de l’API Discourse : https://docs.discourse.org/.
Un guide utile pour déterminer comment structurer les requêtes API : Comment rétro-ingénierer l’API Discourse.
.
