Périmètres

Un périmètre est une permission que tu coches sur une clé. Il s'écrit <famille>:<nature>, par exemple students:read. Une clé ne fait que ce que ses périmètres permettent : sans le bon, l'API répond 403 SCOPE_MISSING.

Familles et natures

Tes données sont rangées en familles. Chaque famille a trois natures : Lire (:read), Écrire (:write) et Supprimer (:delete), y compris les bilans, qui n'ont pourtant aucune opération de suppression. Ce sont les cases de Paramètres › Intégrations › Clés API. Le tableau montre ce que chaque famille ouvre par l'API.

activity:read (lecture seule, pas une famille) ouvre /coaching-timeline.

webhooks:read lit tes webhooks et leurs envois, et ouvre tous les types d'événements ; webhooks:write crée, modifie, change le secret, teste et renvoie ; webhooks:delete supprime. Une clé ne gère que les webhooks dont elle peut lire tous les événements : sans webhooks:read, chaque type demande la lecture de sa famille, par exemple bilans:read pour bilan.submitted. GET /events est gratuit et ne rend que les types que la clé lit : tous avec webhooks:read, sinon ceux des familles qu'elle lit. Tout est détaillé dans Webhooks.

POST /operations/<nom> exécute toutes les opérations de GET /operations, dans toutes les familles ; trois restent propres au MCP : programs.assign et mealplans.assign (ils consomment leur source), bilans.photo (une image). GET /operations donne pour chacune sa nature (kind) et son périmètre (scope).

Supprimer exige Écrire

:delete suppose :write de la même famille. Quand tu coches Supprimer, l'app coche Écrire pour toi, et elle refuse une clé qui porte l'un sans l'autre (400 INVALID_SCOPE). Une clé qui écrit (:write ou :delete) demande aussi que tu aies accepté la version en vigueur des conditions d'usage.

Si ton offre n'ouvre pas les écritures, l'API répond 403 WRITE_NOT_ALLOWED, même avec le bon périmètre.

Périmètres sensibles

Un périmètre est sensible quand il ouvre des données personnelles ou de santé, ou qu'il change ton compte. L'app le marque « sensible » : n'en coche que ce dont l'outil a besoin. Tous les périmètres d'écriture et de suppression le sont, ainsi que ces lectures :

Pour une opération, GET /operations liste ces périmètres dans sensitive : la clé les exige en plus de scope, quels que soient les arguments. students.read, students.list, students.get et students.requests demandent donc students.contact:read, alors que GET /students répond sans lui, sans email ni phone. Les autres opérations répondent sans lui, mais sans aucune adresse e-mail ni aucun numéro : un fil de messagerie ou un programme nomme l'élève sans ses coordonnées, et une fiche de prospect arrive sans email ni contactHandle. prospects.read avec view=search répond alors 400 VALIDATION, car la recherche porte aussi sur email et contactHandle. prospects.invite répond 400 VALIDATION lui aussi, sauf si l'appel passe l'adresse dans email.

Équipe

team:read étend les routes de lecture de toutes les familles aux données des entraîneurs actifs des équipes dont tu es propriétaire. Le coach_id de chaque élève nomme son coach. Il n'est accepté que pour le propriétaire d'une équipe.

Quand un périmètre manque

L'API répond 403 SCOPE_MISSING, et details.scope nomme le périmètre à ajouter :

{
  "error": {
    "name": "PARTNER_API",
    "message": "SCOPE_MISSING",
    "details": { "scope": "students:write" }
  }
}

Un 403 ne coûte aucun crédit. Comme on ne modifie pas une clé, ajoute ce périmètre sur une nouvelle clé. Les écritures sont détaillées dans Écritures et idempotence.