To use this API, you must first acquire an authentication token. This indicates that you have permission from the user that you can use the API on their behalf. The first section here explains how to get tokens.

Tokens can be limited so that they do not have permission to do everything on behalf of a user. The second sections explains token permissions.

Once an authentication token has been acquired, each request to the API must include the token, and the third section explains this.

Getting authentication tokens

There are a number of ways to get an access token. Which one you should use depends on how you’re using the API — whether you have a web app, mobile app, desktop app or are just playing around with the API.

All but the last option (manually creating tokens) require an app to have first been registered. See app creation for details about this.

Server based web authentication

Use this approach if you have a website where you control what runs on the server.

The authentication token can then be used to make requests to the API.

Mobile and browser based web authentication

Use this approach if you have a mobile app or a website where everything is done in JavaScript.

If you have a mobile app, use a custom protocol handler so that the OAuth redirect URL can communicate the authentication token to your app. For example, your OAuth redirect URL might be ca00000000://authorise

Note that the API doesn’t yet support JSONP or have cross-origin resource sharing set up, which means browser based web applications will need to make all API calls via a server anyway.

Manually creating tokens

permissions is a comma separated list of permissions. See below for more details.

If you have a team account, you can create an authentication token for your team:

>>> POST /tokens {permissions: 'all', team_id: <team_id>}

A team token can be used to interact with all accounts that the team owns.

Note: GET /tokens retrieves a list of tokens.

Token permissions

Tokens can be limited so that they have permission to perform only certain functions on behalf of a user. The scope parameter must be included when a token is created, and it must include a comma separated list of the following values:

Access granted to

Read

Read and write

Create

Name, timezone, units, sex etc.

read_account

modify_account

Email address

read_email

modify_email

FTP, heart rate and weight history,power and heart rate zones

read_athlete

modify_athlete

Rides

read_rides

modify_rides

create_rides

There is also a special value, all which gives the token all these permissions and more, such as being able to access and create tokens.

There is no need to request both read_ and modify_ permissions, as modify_ includes permission to read. If create_rides is granted, the token can upload new rides, but can’t read or modify any existing rides.

Using authentication tokens

Once an authentication token has been acquired, requests must include the token in the Authorization HTTP header in the following way: