Authentication
The two credential types, how bearer auth works, and what revocation guarantees.
Every request to the Mouve API is authenticated with a bearer token:
Authorization: Bearer <token>There are two ways to get one. Both are governed by the same scope catalog and the same rate-limit model.
| OAuth 2.1 app | Personal access token | |
|---|---|---|
| For | Apps other people connect | Your own account: scripts, agents, self-hosted tools |
| Token | Short-lived access token (1 hour) + rotating refresh token | Long-lived secret (mouve_pat_…) |
| Consent | Per-user consent screen listing exact scopes | You choose scopes at creation |
| Acts as | The user who granted access | You |
One account, explicit permissions
A token always acts as a specific Mouve user, and can do exactly what its
scopes allow — nothing more. There is no scope hierarchy and no implication:
posts.write does not include posts.read; request both if you need both.
Endpoints that manage credentials or apps (creating tokens, editing app settings, admin surfaces) accept no API token of any kind. They are session-only in the product UI, so a stolen token can never mint further credentials.
Revocation is immediate
Every request re-checks, against the database, that:
- the app is still active (not disabled or taken down),
- the user's account is in good standing, and
- for OAuth — the user's grant still exists; for PATs — the token is not revoked or expired.
The consequence you can state to your users truthfully: access ends
immediately when they disconnect your app — including access tokens that
were minted seconds earlier. Design for 401 TOKEN_REVOKED appearing at any
time, and treat it as "re-authorize or stop", never as a transient error to
retry.
401 responses carry a WWW-Authenticate: Bearer header. The full
401-vs-403 discipline (which failures mean "get a new token" and which mean
"you lack permission") is specified in errors.
What tokens never grant
- No access to other users' private data — reads are visibility-checked as the acting user on every row.
- No email addresses, dates of birth, or body measurements through any REST endpoint — profile projections exclude them unconditionally.
- No health data over REST at all in v1. Workouts, nutrition, and body metrics are exposed only as consent-gated MCP tools.