Scopes
The complete permission catalog — exact-match, no hierarchy, health data explicitly marked.
Scopes are the only permission model in the Mouve API. They apply identically to OAuth grants and personal access tokens.
Three rules, with no exceptions:
- Exact match. A route or tool requires specific scopes; the token must hold every one of them. There is no hierarchy and no wildcard.
- Write does not imply read.
posts.writealone cannot fetch a post. - Unlisted means unreachable. Endpoints with no public scope —
credential management, app settings, admin, the entire internal API —
reject every API token with
403 TOKEN_NOT_PERMITTED.
What a user sees on the consent screen is the Grants text below, verbatim. Request the smallest set that does the job — over-asking is the most common reason users decline a connection.
Catalog
| Scope | Grants | Health data |
|---|---|---|
profile.read | See your profile: username, display name, bio, avatar, and follower counts | — |
profile.write | Edit your profile: display name, bio, location, website, and avatar | — |
body.read | See your body measurements: height, weight, and body-fat history | yes |
body.write | Record body measurements (height, weight, body fat) for you | yes |
follows.write | Follow and unfollow people as you | — |
posts.read | See your feed and the posts, comments, and likes you can see | — |
posts.write | Create posts and replies — with images — and delete your posts, as you | — |
workouts.read | See your workouts, training history, and the exercise library | yes |
workouts.write | Create workouts and log training sessions for you | yes |
nutrition.read | See your nutrition data and use food search and AI food analysis | yes |
nutrition.write | Log meals and nutrition entries for you | yes |
notifications.read | See your notifications and recent activity | — |
memory.read | Read what connected assistants remember about you | — |
memory.write | Save memories about you for connected assistants | — |
world.read | Find outdoor gyms near a place and plan routes to them | — |
world.write | Send planned routes to your Mouve app (kept 7 days) | — |
Notes:
- There is no media scope. Media exists only to attach to posts, so
POST /public/v1/mediarequiresposts.writeandGET /public/v1/media/:idrequiresposts.read. - REST vs. MCP. The REST surface in v1 binds only
profile.read,posts.read, andposts.write. Every other scope currently binds MCP tools — most notably all health scopes. - All scopes are available to personal access tokens. The one class that must never be token-reachable (credential and app management) has no scope at all — the stronger guarantee.
Health data
Scopes marked yes cover data that is special-category under GDPR Article 9 (health). For these, Mouve additionally requires:
- an explicit, separate acknowledgement on the consent screen (or at PAT creation), recorded as a consent record tied to your app or token;
- a registered privacy policy URL on the requesting app;
- the contractual handling rules in the Developer Terms — purpose-bound use, deletion on revocation, no sale or advertising use.
If a user withdraws health-data consent, every grant and token of yours that holds a health scope is revoked in full — your app can re-authorize without the health scopes.
Cross-user reads
Scopes gate capabilities, not visibility. Reading another user's profile or posts is always additionally filtered by what the acting user is allowed to see — private profiles stay private, and profile projections never include email, date of birth, or body measurements across users, under any scope.