Une clé d'intégration est ce qui laisse entrer votre système — et lui seul — dans les données de votre établissement. Ce guide explique comment en poser une, choisir ce qu'elle ouvre, et la couper si elle fuit. Chaque route est détaillée dans la référence : Clés d'intégration.
Poser une clé
Un administrateur de l'établissement pose la clé, depuis l'écran d'administration ou par l'API, avec sa session :
POST /api/institutions/:institutionId/keys
{ "label": "ENT — émargement",
"scopes": ["attendance:read"],
"expiresAt": "2027-09-01T00:00:00Z"
}:institutionId est l'identifiant de l'établissement : GET /api/me le rend, avec la session, dans institutions.
La réponse contient la clé en clair, dans plaintext. C'est la seule fois : MeetingHub n'en garde qu'une empreinte, et personne ne pourra vous la redonner. Copiez-la tout de suite dans la configuration de votre système.
Donnez-lui un nom qui dit à quoi elle sert. Le nom est obligatoire : une clé sans nom est une clé que personne n'ose plus révoquer, faute de savoir ce qui casserait.
L'échéance est facultative. Un ENT branché pour de bon n'a pas à casser tous les six mois ; une clé posée pour un essai, si.
Choisir les portées
Une clé n'ouvre que ce que ses portées permettent :
| Portée | Ce qu'elle permet |
|---|---|
attendance:read | Lire les feuilles de présence |
schedule:read | Lire l'emploi du temps |
schedule:write | Déposer l'emploi du temps et annuler des cours |
roster:write | Déposer des listes d'inscrits, et donc créer des comptes |
Donnez à chaque système les seules portées dont il a besoin. Un outil qui ne fait qu'archiver les feuilles de présence n'a besoin que de attendance:read ; s'il fuit, il n'expose rien d'autre. Les deux portées d'écriture méritent une attention particulière : roster:write, notamment, rend les liens de première connexion des comptes créés.
Utiliser la clé
Chaque requête porte la clé dans l'en-tête Authorization :
Authorization: Bearer mhk_Abdvt1rV_47R9xK2pQ…Commencez par GET /api/me : il confirme que la clé est valide, rend l'identifiant de son établissement et ce qu'elle ouvre, dans capabilities. Chaque portée y apparaît comme une capacité : attendance:read devient attendance.read, schedule:write devient schedule.write. Une requête qui demande une capacité que la clé n'a pas est refusée avec 403, et le message nomme la capacité manquante.
N'envoyez pas de cookie de session avec la clé : une requête qui porte les deux est refusée avec 400.
Les appels sont limités à 300 par minute et par clé. Au-delà, la réponse est 429 avec un en-tête Retry-After : attendez le nombre de secondes indiqué.
Ce qui est journalisé
Chaque requête qui aboutit avec une clé est inscrite au journal de l'établissement, lectures comprises : une feuille de quatre cents noms qui sort est une extraction de données personnelles, et c'est précisément l'acte qu'on veut pouvoir retrouver.
La trace nomme la clé, et recopie son nom : même supprimée, une clé laisse la trace de ce qu'elle a fait. Le journal d'une clé se lit avec GET /api/institutions/:institutionId/keys/:keyId/activity.
Les requêtes refusées — clé invalide, capacité absente — ne sont pas inscrites.
Révoquer une clé
DELETE /api/institutions/:institutionId/keys/:keyIdLa clé est coupée dès la requête suivante. Elle n'est pas supprimée pour autant : elle reste listée avec sa date de révocation, et son journal reste lisible.
Si une clé fuite
Une clé commence par mhk_, et ses huit caractères suivants sont lisibles en clair dans la liste des clés : c'est ce qui permet de la reconnaître dans un dépôt de code ou un journal. Révoquez-la, posez-en une nouvelle, puis lisez le journal de l'ancienne pour savoir ce qui a été fait avec elle.