Authentication for this API is based on the OAuth 2.0 framework.
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.
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.
Use this approach if you have a website where you control what runs on the server.
Send the user to:
https://www.cyclinganalytics.com/api/auth?response_type=code&client_id=...&scope=...
Where:
client_id is the id of your app. This can be found on the app settings page.scope is a comma separated list of permissions that your app is requesting access to. See below for information about token permissions.If the user grants your app permission, they will be redirected to the app’s OAuth redirect URL, with a code query string parameter:
<redirect_url>?code=...
If an error occured, an error query string will be present instead:
<redirect_url>?error=...
Next, exchange the code for an authentication token with a call to:
https://www.cyclinganalytics.com/api/token?grant_type=authorization_code&code=...&client_id=...&client_secret=...
Where:
code has the same value as was returned by the previous call.client_id is your app’s id.client_secret is your app’s secret key.If this was successful, an authentication token is returned as JSON:
{"access_token": "..."}
If an error occured, an error message is returned:
{"error": "..."}
The authentication token can then be used to make requests to the API.
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.
Send the user to:
https://www.cyclinganalytics.com/api/auth?response_type=token&client_id=...&scope=...
Where:
client_id is the id of your app. This can be found on the app settings page.scope is a comma separated list of permissions that your app is requesting access to. See below for information about token permissions.If the user grants your app permission, they will be redirected to the app’s OAuth redirect URL, with an authentication token provided in the token parameter in the fragment:
<redirect_url>#token=...
If an error occured, an error will be present in the fragment instead:
<redirect_url>#error=...
The authentication token can then be used to make requests to the API.
This approach should only be used if the other approaches are unsatisfactory, such as with desktop applications.
Request an authentication token with a call to:
https://www.cyclinganalytics.com/api/token?grant_type=password&client_id=...&username=...&password=...&scope=...
Where:
client_id is your app’s id.username is the email address that the user logs in with.password is the user’s password.scope is a comma separated list of permissions that your app is requesting access to. See below for information about token permissions.If this was successful, an authentication token is returned as JSON:
{"access_token": "..."}
If an error occured, an error message is returned:
{"error": "..."}
The authentication token can then be used to make requests to the API.
You can create a token for youself with the API console using the /tokens method:
>>> POST /tokens {permissions: 'all'}
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.
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.
Once an authentication token has been acquired, requests must include the token in the Authorization HTTP header in the following way:
Authorization: Bearer qr4hI35VeCmOfPAQhXSHGNX5JZcsJyIP
There are examples of this in the quickstart guide.