Scopes

A scope is a permission you tick on a key. It is written <family>:<kind>, for example students:read. A key does only what its scopes allow: without the right one, the API answers 403 SCOPE_MISSING.

Families and kinds

Your data is organized in families. Each family has three kinds: Read (:read), Write (:write) and Delete (:delete), check-ins included, although they have no delete operation. These are the boxes of Settings › Integrations › API keys. The table shows what each family opens through the API.

activity:read (read only, not a family) opens /coaching-timeline.

webhooks:read reads your webhooks and their deliveries, and opens every event type; webhooks:write creates, updates, changes the secret, tests and redelivers; webhooks:delete deletes. A key manages only the webhooks whose events it can all read: without webhooks:read, each type requires the read scope of its family, for example bilans:read for bilan.submitted. GET /events is free and returns only the types the key reads: all of them with webhooks:read, else those of the families it reads. Everything is detailed in Webhooks.

POST /operations/<name> runs every operation of GET /operations, in every family; three stay specific to the MCP: programs.assign and mealplans.assign (they consume their source), bilans.photo (an image). GET /operations gives each one its kind (kind) and its scope (scope).

Delete requires Write

:delete requires :write of the same family. When you tick Delete, the app ticks Write for you, and it refuses a key that holds one without the other (400 INVALID_SCOPE). A key that writes (:write or :delete) also needs you to have accepted the current version of the terms of use.

If your plan does not include writes, the API answers 403 WRITE_NOT_ALLOWED, even with the right scope.

Sensitive scopes

A scope is sensitive when it opens personal or health data, or changes your account. The app marks it "sensitive": tick only what the tool needs. Every write and delete scope is sensitive, and so are these reads:

For an operation, GET /operations lists these scopes in sensitive: the key needs them in addition to scope, whatever the arguments. So students.read, students.list, students.get and students.requests require students.contact:read, while GET /students answers without it, with no email or phone. The other operations answer without it, but with no e-mail address and no phone number: a messaging thread or a program names the student without their contact details, and a prospect record comes without email or contactHandle. prospects.read with view=search then answers 400 VALIDATION, because the search also matches email and contactHandle. prospects.invite answers 400 VALIDATION too, unless the call passes the address in email.

Team

team:read widens the read routes of every family to the data of the active trainers of the teams you own. The coach_id of each student names the coach. It is accepted only for the owner of a team.

When a scope is missing

The API answers 403 SCOPE_MISSING, and details.scope names the scope to add:

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

A 403 costs no credit. Since you do not edit a key, add this scope on a new key. Writes are detailed in Writes and idempotency.