Permission Scopes
Reference for OAuth 2.0 permission scopes available in the Coach Watts API and MCP server.
When requesting authorization, specify which scopes your application needs. Users see these permissions on the consent screen and can deny access they are uncomfortable with.
REST API scopes
| Scope | Description | Access |
|---|---|---|
profile:read | Default. Read public profile info | Name, email, avatar, FTP |
profile:write | Update profile settings | Weight, FTP, preferences |
workout:read | Read workout history | List workouts, get details |
workout:write | Manage workouts | Upload, edit, delete workouts |
health:read | Read health metrics | HRV, sleep, recovery scores |
health:write | Log health metrics | HRV, sleep, weight |
nutrition:read | Read nutrition logs | Daily calories, macros |
nutrition:write | Log nutrition data | Calories, carbs, protein |
offline_access | Long-lived access | Returns a refresh_token |
MCP scopes
These scopes apply to the remote MCP server at /mcp. See MCP Server for setup.
| Scope | Description |
|---|---|
planning:read | Read planned workouts, availability, and current plan |
planning:write | Create and modify planned workouts |
analysis:read | Training load analysis and forecasts |
memory:read | List stored AI memories |
memory:write | Create, update, or forget memories |
recommendations:read | Read recommendations |
recommendations:write | Accept or dismiss recommendations |
ai:generate | Reserved for future async/AI tools |
MCP also reuses the profile, workout, health, and nutrition scopes above.
Best practices
- Least privilege — only request scopes your app actually uses
- Incremental auth — request additional scopes later when the user attempts a specific action
- Explain why — tell users on your app's connect screen what data you need and why
Example authorization request
GET /api/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_REDIRECT_URI
&scope=profile:read workout:read health:read offline_access
&state=RANDOM_STRING
&code_challenge=PKCE_CHALLENGE
&code_challenge_method=S256