Authentication

Scopes

Every endpoint requires a scope, and a token carries only what was granted. Users see the exact scopes an app requests — ask for the minimum you need.

Available scopes

Scope	Grants access to
`profile:read`	Display name, username, units, gender, height, goal
`workouts:read`	Workout history, workout detail (exercises & sets), workout templates
`records:read`	Personal records (1RM, weight, volume, reps, duration, distance)
`measurements:read`	Body weight and circumference measurements
`stats:read`	Streaks, total XP and trophies
`splits:read`	Custom training splits
`exercises:read`	The global exercise and equipment catalogs

The API is read-only today — there are no write scopes. Write access will be introduced as explicit new scopes, never folded silently into existing ones.

Enforcement

Scopes are enforced server-side on every request. Calling an endpoint your token wasn’t granted returns 403 with a problem-details body:

GET /api/v1/measurements
Authorization: Bearer gat_…   (granted: workouts:read stats:read)

HTTP/1.1 403 Forbidden
{
  "status": 403,
  "title": "Missing scope",
  "detail": "This authorization is missing the 'measurements:read' scope."
}

Defaults

Token type	Default scopes
Personal token	All scopes, unless you narrow them at creation — it’s your own data.
OAuth app	Only the scopes registered for your app and consented to by the user.
MCP connection	A fixed scope set granted when you connect your account; enforced per tool call.