Référence — éditeurs partenaires

Ce qu'un éditeur partenaire fait sur /api avec sa clé :

Authorization: Bearer mhp_Q3x9LmPa_…

La clé a la même forme qu'une clé d'intégration, avec le préfixe mhp_. Elle ouvre deux sortes de routes :

• les routes de l'éditeur lui-même, qui exigent une clé d’éditeur dans la table des routes : ouvrir un établissement, poser ses webhooks, lire sa mesure d'usage. Appelées par un autre appelant, elles répondent 403, réservé aux éditeurs partenaires ;
• dans chaque établissement qu'il a ouvert, les routes qui exigent institution.view ou partner.manage : lire l'établissement, déclarer ses centres, poser ses clés, demander des liens d'entrée.

Elle n'ouvre ni l'emploi du temps, ni les feuilles de présence, ni les listes d'inscrits : pour cela, l'éditeur pose dans l'établissement une clé mhk_…, et son logiciel l'utilise ensuite. Voir Clés d'intégration.

Un établissement que l'éditeur n'a pas ouvert répond 404, comme s'il n'existait pas. Un établissement en pause ne lui ouvre plus que la lecture : ses écritures y sont refusées en 403, cet accès ne permet pas cela — il faut : institution.manage ou partner.manage. Chaque requête de l'éditeur dans un de ses établissements, lectures comprises, est inscrite au journal de cet établissement, au nom éditeur partenaire « … ».

Les corps JSON font 4 Mo au plus, et chaque éditeur fait 300 requêtes par minute au plus ; au-delà, la réponse est 429. Voir Conventions.

Échecs d'authentification

Les réponses 401 d'une clé fautive portent l'en-tête WWW-Authenticate: Bearer error="invalid_token". Une clé d'éditeur n'a pas d'échéance : elle vaut jusqu'à ce que l'exploitant la révoque.

L'objet Établissement

{
  "id": "6c1d3a52-7a0e-4f0b-9c55-0a54c3e1f2b8",
  "slug": "lycee-bilingue-bonamoussadi",
  "name": "Lycée bilingue de Bonamoussadi",
  "kind": "school",
  "status": "active",
  "trialEndsAt": null,
  "createdAt": "2026-10-01T08:00:00.000Z"

}

GET /api/me

Avec une clé d'éditeur :

{
  "actor": { "kind": "partner-key", "id": "…", "name": "Votre logiciel" },
  "institutions": [{ "id": "6c1d3a52-…", "name": "Lycée bilingue de Bonamoussadi", "status": "active" }],
  "capabilities": ["institution.view", "partner.manage"]

}

actor.id et actor.name sont ceux de l'éditeur, pas de la clé. institutions liste les établissements qu'il a ouverts.

GET /api/institutions

Les établissements que vous avez ouverts, par ordre alphabétique.

Réponse 200 : { "institutions": [Établissement] }. Le status rendu tient compte d'un essai échu.

POST /api/institutions

Ouvre un établissement pour un de vos clients. Exige une clé d'éditeur.

{
  "slug": "lycee-bilingue-bonamoussadi",
  "name": "Lycée bilingue de Bonamoussadi",
  "kind": "school",
  "sandbox": true,
  "admin": { "email": "direction@lycee.cm", "displayName": "Direction" }

}

Le premier responsable reçoit le rôle promoter : le Promoteur, qui gouverne l'établissement. S'il n'a pas de compte, un compte est créé, sans mot de passe connu, avec un lien d'activation pour qu'il choisisse le sien.

Réponse 201 :

{
  "organisation": { "id": "…", "slug": "…", "status": "trial", "…": "…" },
  "admin": { "email": "direction@lycee.cm", "invited": true, "link": "https://reunion.exemple.cm/app/?setup=…" }

}

Vos webhooks d'éditeur sont recopiés dans l'établissement dès son ouverture.

GET /api/institutions/:institutionId

L'établissement, et ce que vous pouvez y faire.

{
  "institution": { "id": "6c1d3a52-…", "name": "Lycée bilingue de Bonamoussadi", "status": "active", "trialEndsAt": null },
  "capabilities": ["institution.view", "partner.manage"],
  "support": false

}

En pause, capabilities ne contient plus que institution.view.

L'objet Centre

GET /api/institutions/:institutionId/centres

Les centres de l'établissement. Exige institution.view. Réponse 200 : { "centres": [Centre] }.

POST /api/institutions/:institutionId/centres

Déclare un centre. Exige partner.manage — ou, pour l'établissement, institution.manage.

{ "name": "Campus de Kotto", "reference": "KOT", "city": "Douala" 
}

Réponse 201 : { "centre": Centre }.

Renommer ou retirer un centre, et nommer ses directeurs, reviennent à l'administration de l'établissement.

Les clés de vos établissements

GET, POST et DELETE sous /api/institutions/:institutionId/keys : mêmes routes, mêmes corps et mêmes réponses que pour l'établissement — voir POST /api/institutions/:institutionId/keys et L'objet Clé. Avec trois différences :

• vous ne voyez et ne révoquez que les clés que vous avez créées ; une autre répond 404, clé inconnue. Elles portent votre identifiant dans partnerId ;
• sans accord sur les données personnelles, attendance:read et roster:write vous sont refusées à la création : 403, portée réservée aux éditeurs partenaires sous accord de données personnelles : …. L'exploitant lève cette restriction une fois l'accord de sous-traitance signé. Si l'accord vous est retiré ensuite, vos clés perdent ces deux portées dès leur requête suivante ;
• le journal d'une clé, GET …/keys/:keyId/activity, reste réservé à l'administration de l'établissement.

{ "label": "Votre logiciel — emploi du temps", "scopes": ["schedule:read", "schedule:write"] 
}

La clé en clair est rendue dans key.plaintext, cette fois seulement.

POST /api/institutions/:institutionId/entries

Un lien d'entrée dans une salle de l'établissement, à ouvrir dans une iframe. Exige une clé d'éditeur et partner.manage.

{ "room": "ABCD2345", "displayName": "Awa Ngono", "host": false, "ttlMinutes": 120 
}

Réponse 201 :

{
  "entry": {
    "token": "eyJvIjoi….1791000000.Xk2…",
    "url": "https://reunion.exemple.cm/app/?room=ABCD2345&entree=…",
    "expiresAt": "2026-10-14T10:00:00.000Z"
  }

}

À l'entrée, le lien tient lieu de politique d'entrée et de mot de passe. Il ne passe outre ni l'horaire du cours, ni le verrou, ni la salle d'attente, ni une exclusion. La page ne se laisse encadrer que par vos origines enregistrées (Content-Security-Policy: frame-ancestors).

L'objet Webhook d'éditeur

GET /api/partner/webhooks

Vos webhooks. Réponse 200 : { "webhooks": [Webhook], "events": [string] }. Le champ events liste tous les événements qui existent.

POST /api/partner/webhooks

{ "url": "https://api.votre-logiciel.cm/meetinghub", "events": ["attendance.closed"], "label": "Production" 
}

Mêmes règles d'adresse et d'événements que pour un webhook d'établissement : voir Webhooks. Le webhook est recopié dans chacun de vos établissements, présents et à venir ; chaque appel porte l'identifiant de l'établissement dans organisationId.

Réponse 201 : { "webhook": Webhook, "notice": "…" }. Le secret de signature est dans webhook.secret, cette fois seulement.

PATCH /api/partner/webhooks/:webhookId

Change url, events ou label. Toutes les copies suivent ; ce qui est propre à un établissement — un webhook coupé après trop d'échecs — reste le sien. Réponse 200 : { "webhook": Webhook }. Un webhook inconnu répond 404, alerte inconnue.

DELETE /api/partner/webhooks/:webhookId

Supprime le webhook et toutes ses copies. Réponse 204. Un webhook inconnu répond 404, alerte inconnue.

GET /api/partner/usage

Ce que chaque établissement a consommé sur un mois calendaire, en UTC.

Réponse 200 :

{
  "month": "2026-10",
  "from": "2026-10-01T00:00:00.000Z",
  "to": "2026-11-01T00:00:00.000Z",
  "organisations": [
    {
      "organisationId": "…",
      "name": "Lycée bilingue de Bonamoussadi",
      "status": "active",
      "rooms": 12,
      "connections": 1840,
      "participants": 410,
      "seconds": 2952000,
      "bytes": 61200000000,
      "sessionsHeld": 96
    }
  ]

}

Aucun nom, aucune adresse : ce sont des totaux.

Les anciennes adresses

Les routes /api/partner/… répondent encore, avec une clé d'éditeur seulement, comme alias dépréciés : chaque réponse porte Deprecation: true et un en-tête Link vers la route qui la remplace. Sans clé d'éditeur, elles répondent 401, clé d’éditeur partenaire requise, code auth.required.

Les réponses sont celles de /api : GET /api/partner/organisations rend donc institutions, et la liste des centres centres.