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
Please mail the following info to david@intervals.icu:
- App name
- Description
- Website URL
- Logo image URL
- Privacy policy URL
- Redirect URI (http://localhost/ is always allowed)
Contact me (David) via Intervals.icu chat (“Ask a coach” box) and let me know you have sent the mail. This will also indicate who you are on Intervals.icu.
Once your application has been created you will receive a client_id and client_secret. The client_id is public information but the client_secret needs to be carefully protected.
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. Endpoints will generally also include the athlete id in the path.
Scopes
Scopes are as follows:
- ACTIVITY: Completed rides, runs etc.
- WELLNESS: Weight, resting HR etc.
- CALENDAR: Planned workouts
- 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.
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.
