RunfolioApp

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_VALUE

The 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_SECRET

The 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.

RequestReturns
GET /api/v1/athleteThe account id.
GET /api/v1/activitiesActivities, 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/IDOne activity and its track: GPS points with time, latitude, longitude, accuracy, altitude, speed and the Android mock-location flag.
POST /api/oauth/deauthorizeEnds 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