Intervals.icu uses OAuth2 for authentication to the API. OAuth allows external applications to request authorization to access an Intervals.icu user’s data. It allows users to grant and revoke API access on a per-application basis and keeps user authentication details safe.
Creating An Application
Fill in the application form here: https://intervals.icu/oauth/apply
You need to be logged in as the Intervals.icu athlete that will own the app. This athlete will have access to the management page to edit the app, setup redirect URI’s, webhooks and other things.
Your app will show up on the /settings/apps page (only for you as the owner) and you can click “Manage App” to retrieve your client_id and secret, change redirect URL’s, configure webhooks and so on.
The app will have status “Pending” until it is approved. Please note that you will not be able to do the OAuth flow until it is approved. You can upload a logo, get the client ID and secret and so on.
Once it has been approved, the pending tag will disappear. You will receive a system notification when this happens (delivered by email and in the Intervals.icu app).
Note that it will not be visible to other users in /settings/apps, but you can send anyone you like to the OAuth consent page and begin integration.
When you have completed your integration and tested properly, contact [email protected] to have it listed in the public app directory. Please include a link to the management page in the email.
Requesting Authorization To Access Intervals.icu Data For A User
Send the user to:
https://intervals.icu/oauth/authorize?client_id=<your client id>
&redirect_uri=<your redirect uri>
&scope=<required scopes>
&state=<optional data>
Intervals.icu will ask the user to login and display a confirmation dialog with options to choose which
scopes to grant the application. If the user confirms then they are redirected to the redirect_uri with an
authorization code and the optional state parameter:
<your redirect uri>?code=3983ed415f66413c890ca48b7cce59e4&state=...
If they decline:
<your redirect uri>?error=access_denied
Your server needs to exchange the code for an access token within 2 minutes by POSTing form data including your client_id and client_secret:
curl -X POST https://intervals.icu/api/oauth/token \
-d client_id=... \
-d client_secret=... \
-d code=3983ed415f66413c890ca48b7cce59e4
If all goes well Intervals.icu will respond with an access token, granted scopes and the id and name of the athlete:
{
"token_type": "Bearer",
"access_token": "d842c1fc25f241e5ae440d09756448a9",
"scope": "ACTIVITY:WRITE,WELLNESS:WRITE",
"athlete": {
"id": "2049151",
"name": "David (intervals.icu)"
}
}
To call the API use “Authorization: Bearer d842c1fc25f241e5ae440d09756448a9” header.
Note that you can use “0” for the athlete id for endpoints that accept an athlete id in the path. This will use the athlete for the bearer token used to make the call.
Scopes
Scopes are as follows:
- ACTIVITY: Completed rides, runs etc.
- WELLNESS: Weight, resting HR etc.
- CALENDAR: Planned workouts
- CHATS: Chats, groups and messages
- LIBRARY: Workout library
- SETTINGS: Athlete settings
For each scope specify READ or WRITE (to update, implies READ access) and use commas to separate multiple scopes. Example:
ACTIVITY:READ,WELLNESS:WRITE
Requests read access to activities and read and write access to wellness data.
Revoking An Access Token
When a user disconnects Intervals.icu in your app or deletes their data on your side, revoke the access token:
curl -X DELETE "https://intervals.icu/api/v1/disconnect-app" \
-H 'authorization: Bearer d842c1fc25f241e5ae440d09756448a9'
This will stop webhook delivery for the athlete.
Your Own Data
Note that you don’t need to do all this if you just want access to your own data. Use your API key to do that.
