Référence — clés d'intégration

Les routes de gestion des clés, sous /api/institutions/:institutionId/keys, demandent la session d'un administrateur de l'établissement — la capacité institution.manage : voir Conventions. Un éditeur partenaire les appelle aussi, avec sa clé mhp_…, sur les établissements qu'il a ouverts : il ne voit et ne révoque que les clés qu'il a créées lui-même. Voir Éditeurs partenaires.

L'usage d'une clé sur le reste de /api est décrit à la fin de cette page.

L'objet Clé

{
  "id": "2d388508-08af-4066-bc9e-2a705426a434",
  "label": "ENT — émargement",
  "prefix": "Abdvt1rV",
  "scopes": ["attendance:read"],
  "partnerId": null,
  "expiresAt": "2027-09-01T00:00:00.000Z",
  "revokedAt": null,
  "lastUsedAt": "2026-10-14T10:21:00.000Z",
  "createdAt": "2026-09-02T08:00:00.000Z"

}

Le secret de la clé n'est jamais rendu, sauf une fois, à la création, dans le champ plaintext. Le serveur n'en conserve qu'une empreinte.

Portées

Chaque portée devient, à l'usage, une capacité : c'est elle que les routes exigent, et que GET /api/me rend dans capabilities. Toute clé a en plus institution.view, qui ouvre la lecture de son établissement.

Dans ce tableau, … vaut /api/institutions/:institutionId.

GET /api/me, GET /api/institutions et les lectures de l'établissement (GET …, GET …/centres, GET …/room-kinds) ne demandent aucune portée. Il n'existe pas d'autre portée ; une valeur inconnue est refusée à la création de la clé. La liste complète des routes et de ce qu'elles exigent est dans Conventions.

GET /api/institutions/:institutionId/keys

Liste les clés de l'établissement, révoquées comprises. Exige institution.manage ou partner.manage. Un éditeur partenaire ne reçoit que les clés qu'il a créées.

Aucun paramètre de requête.

Réponse 200 :

{
  "keys": [ { "id": "…", "label": "ENT — émargement", "partnerId": null, "…": "…" } ],
  "scopes": ["attendance:read", "schedule:read", "schedule:write", "roster:write"]

}

POST /api/institutions/:institutionId/keys

Crée une clé et la rend en clair, une seule fois. Exige institution.manage ou partner.manage.

{
  "label": "ENT — émargement",
  "scopes": ["attendance:read", "schedule:write"],
  "expiresAt": "2027-09-01T00:00:00Z"

}

Réponse 201 :

{
  "key": {
    "id": "2d388508-08af-4066-bc9e-2a705426a434",
    "label": "ENT — émargement",
    "prefix": "Abdvt1rV",
    "scopes": ["attendance:read", "schedule:write"],
    "partnerId": null,
    "expiresAt": "2027-09-01T00:00:00.000Z",
    "revokedAt": null,
    "lastUsedAt": null,
    "createdAt": "2026-09-02T08:00:00.000Z",
    "plaintext": "mhk_Abdvt1rV_47R9xK2pQ…"
  },
  "notice": "Cette clé ne sera plus affichée. Copiez-la maintenant."

}

Ces refus portent le code invalid (400) ou forbidden (403).

DELETE /api/institutions/:institutionId/keys/:keyId

Révoque une clé. Exige institution.manage ou partner.manage. La clé n'est pas supprimée : elle reste listée, avec sa date de révocation, et son journal reste consultable.

Réponse 200 :

{ "key": { "id": "…", "revokedAt": "2026-10-20T09:00:00.000Z", "…": "…" } 
}

La révocation est idempotente : révoquer une clé déjà révoquée rend 200 et garde la date de la première révocation. Une clé révoquée est refusée dès la requête suivante.

GET /api/institutions/:institutionId/keys/:keyId/activity

Le journal de ce qu'une clé a fait, du plus récent au plus ancien. Exige institution.manage : l'administration de l'établissement seulement.

Réponse 200 :

{
  "rows": [
    {
      "id": "b0f3…",
      "actorId": null,
      "actorEmail": null,
      "actorKeyId": "2d388508-08af-4066-bc9e-2a705426a434",
      "actorLabel": "ENT — émargement",
      "action": "GET /api/institutions/:institutionId/lessons/:lessonId/attendance.csv",
      "targetType": "/api/institutions/:institutionId/lessons/:lessonId/attendance.csv",
      "targetId": null,
      "metadata": { "status": 200 },
      "at": "2026-10-14T10:21:07.412Z"
    }
  ],
  "total": 1

}

L'objet Trace

Dans metadata, un tableau du corps est remplacé par "[N éléments]" et un objet par "[objet]". Les champs password, roomPassword, token, csv, secret et admin ne sont jamais inscrits.

Ce qui est inscrit. Pour une clé, chaque requête qui aboutit — code de réponse inférieur à 400 —, lectures comprises. Une requête refusée n'est pas inscrite, qu'elle le soit à l'authentification ou ensuite, par exemple faute de capacité.

Échecs d'authentification

Sur /api, la clé se présente dans l'en-tête Authorization: Bearer …, et une requête ne porte qu'un justificatif. Une clé mal formée, inconnue, révoquée ou expirée rend 401, avec un en-tête WWW-Authenticate :

Une clé inconnue et une clé au mauvais secret reçoivent la même réponse, à dessein. Une clé expirée reçoit un message distinct : il faut la remplacer, pas la corriger.

Une clé valide qui appelle une route hors de ses portées reçoit 403, et le message nomme la capacité manquante :

Une clé qui désigne un autre établissement que le sien reçoit 404, code not-found : pour elle, cet établissement n'existe pas.

Sur les anciennes adresses /api/integration/…, alias dépréciés de ces routes, une requête sans clé d'établissement rend 401, clé d’intégration requise, avec l'en-tête WWW-Authenticate: Bearer realm="MeetingHub".