API
A read-only API for services that work with a person's activities, with that person's permission. OAuth 2.0, authorization code flow.
Getting access
Write to support@runfolioapp.xyz with the name of your service, what it does with activities, its website and the redirect addresses you will use. You get a client id and a client secret. The name and description you give are what people see when they are asked to allow access, so they must say plainly what your service does.
1. Ask the person
Send the browser to:
https://runfolioapp.xyz/oauth/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=https://your.service/callback
&response_type=code
&scope=activity:read
&state=RANDOM_VALUEThe person signs in, sees who is asking and for what, and allows or refuses. The browser comes back to your redirect address with code and your state, or with error=access_denied. PKCE is supported: add code_challenge and code_challenge_method=S256.
2. Trade the code for tokens
POST https://runfolioapp.xyz/api/oauth/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&code=THE_CODE
&redirect_uri=https://your.service/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRETThe code works once and for five minutes. The answer has an access_token (six hours), a refresh_token, and athlete.id, a number that identifies the account and never changes. For a new access token send grant_type=refresh_token with the refresh token. Client credentials can also be sent as HTTP Basic.
3. Read activities
Send Authorization: Bearer ACCESS_TOKEN.
| Request | Returns |
|---|---|
GET /api/v1/athlete | The account id. |
GET /api/v1/activities | Activities, newest first. limit up to 200, before and after by start time in milliseconds. With uploadedAfter the list is ordered by the time the server received each activity, oldest first: use it to poll for new ones. |
GET /api/v1/activities/ID | One activity and its track: GPS points with time, latitude, longitude, accuracy, altitude, speed and the Android mock-location flag. |
POST /api/oauth/deauthorize | Ends your access to this account and deletes your tokens for it. |
An activity has id, sport (run or ride), startedAt, endedAt, elapsedS, movingS, distanceM, maxSpeedMs, elevationGainM and uploadedAt. Times are Unix milliseconds.
Rules
- The API is read-only. A token cannot add, change or delete anything.
- A person can disconnect your service at any time. Your tokens for that person then answer 401.
- Email addresses are never part of the API.
- Use the data only for what your description says, and delete it when the person asks you to.