Jetons d'API

• Le jeton d’API en bref
• Conditions préalables
• Trouver les jetons d’API
• Créer un jeton
• Le jeton ne s’affiche qu’une seule fois
• Ce que la liste des jetons affiche
• Révoquer un jeton
• Utiliser le jeton

Le jeton d’API en bref

L’API REST de Klubraum permet à vos propres scripts, au site web de votre association ou à d’autres outils de travailler avec les événements du calendrier et les membres de votre association. Chaque requête s’identifie alors avec un jeton d’accès personnel que vous créez dans l’application Klubraum.

Un tel jeton appartient toujours à un seul Klubraum et à la personne qui l’a créé. Il ne dispose que des champs d’application que vous lui accordez, il peut expirer et vous pouvez le révoquer à tout moment. Surtout, un jeton ne peut jamais faire plus que vous-même : à chaque requête, vos autorisations actuelles dans l’application sont également vérifiées. Si vous perdez une autorisation, le jeton la perd aussi.

Conditions préalables

• Vous êtes administrateur du Klubraum. Les autres membres ne voient pas cette fonction.
• Votre association dispose d’une offre adaptée : la liste des membres, les invitations et les suppressions de membres sont incluses dans Plus, tout autre point de terminaison nécessite Pro. Sans offre adaptée, une indication vous invitant à changer d’offre s’affiche lorsque vous touchez la tuile.

Trouver les jetons d’API

Ouvrez les Paramètres et rendez-vous dans Klubraum actuel. La deuxième tuile s’appelle Jetons d’API, avec le sous-titre Jetons d’accès personnels pour l’API Klubraum, juste en dessous de la tuile permettant de modifier le nom de l’association.

Attention : la tuile juste en dessous concerne le jeton des demandes d’adhésion. Il s’agit d’un autre jeton, prévu uniquement pour le formulaire d’adhésion sur le site de votre association – vous en saurez plus dans Demande d’adhésion sur le site de l’association.

Créer un jeton

Touchez le + en haut à droite (Créer un jeton). La boîte de dialogue Créer un jeton d’API vous demande trois choses.

Nom

Texte libre de 100 caractères maximum, par exemple « Synchronisation du site web ». Donnez à chaque outil son propre jeton et nommez-le d’après cet outil : vous saurez ainsi précisément, plus tard, quel jeton vous pouvez révoquer.

Champs d’application

Vous définissez ici ce que le jeton a le droit de faire. Il existe quatre champs d’application :

• members:read – lire la liste des membres.
• members:write – inviter et supprimer des membres.
• events:read – lire les événements du calendrier.
• events:write – créer, modifier, annuler et supprimer des événements du calendrier.

Un champ d’application en écriture inclut toujours le champ d’application en lecture correspondant. Dès que vous cochez members:write, members:read est coché automatiquement et ne peut plus être décoché ; seul le champ d’application en écriture est alors enregistré sur le jeton. Il en va de même pour events:write et events:read. Au moins un champ d’application est requis.

Astuce : choisissez le moins de champs d’application possible. Un script qui se contente d’afficher vos événements sur votre site web n’a besoin que de events:read.

Expire après

Choisissez 30, 90, 180 ou 365 jours – ou bien Jamais. Avec Jamais, un avertissement s’affiche, et à juste titre : un jeton sans date d’expiration reste valable jusqu’à ce que quelqu’un le révoque. Donnez donc au jeton une durée de vie limitée chaque fois que c’est possible.

Touchez ensuite Créer.

Le jeton ne s’affiche qu’une seule fois

Juste après la création, l’application vous montre le jeton complet : la longue chaîne secrète qui commence par klubraum_pat_. Copiez-la avec le bouton de copie et enregistrez-la immédiatement là où votre script ou votre outil la lit, de préférence dans un gestionnaire de mots de passe ou un coffre à secrets.

Important : c’est le seul moment où la chaîne secrète est visible. Elle ne peut plus être récupérée par la suite, pas même par nous. Si vous la perdez, révoquez le jeton et créez-en un nouveau.

Ne placez jamais la chaîne secrète dans un endroit public : ni dans le JavaScript de votre site web, ni dans un dépôt public, ni dans une conversation de l’association. Toute personne qui la possède peut utiliser l’API avec exactement les champs d’application que vous avez accordés au jeton.

Ce que la liste des jetons affiche

L’écran affiche tous les jetons de votre Klubraum. Pour chacun d’eux, vous voyez :

• le nom que vous lui avez donné,
• un préfixe court commençant par klubraum_pat_, qui identifie le jeton sans révéler la chaîne secrète,
• les champs d’application sous forme de puces,
• la date de création, la date d’expiration et la date de dernière utilisation.

La date de dernière utilisation vous permet de repérer facilement les jetons dont plus personne n’a besoin. Les jetons révoqués restent dans la liste et sont affichés barrés.

Révoquer un jeton

Touchez l’icône de suppression sur le jeton concerné (Révoquer le jeton) et confirmez avec Oui, révoquer. La révocation prend effet immédiatement : à partir de ce moment, chaque requête effectuée avec ce jeton est rejetée. L’opération est irréversible – un jeton révoqué ne peut pas être réactivé.

Astuce : vous souhaitez remplacer un jeton encore utilisé ? Créez d’abord le nouveau jeton, faites basculer votre script ou votre outil dessus, et ne révoquez l’ancien qu’ensuite.

Utiliser le jeton

Envoyez le jeton à chaque requête en tant que bearer token dans l’en-tête Authorization :

Authorization: Bearer klubraum_pat_…

Les points de terminaison existants, les paramètres qu’ils attendent et ce qu’ils renvoient sont décrits dans la section développeurs et dans la référence de l’API interactive. En anglais.