We use standard OAuth2 authentication.
Below is a quick guide to authenticating. If you're not familiar with OAuth2 it might be a good idea to read Aaron Parecki's excellent article: OAuth2 Simplified.
Server Authentication
Step 1. Obtain the user's permission to access their data
When your users choose to connect to SportTracks you'll need to first direct them to the SportTracks authentication page.
Using the client credentials you received when applying to use the API, obtain an authorization code by directing your users here:
Note: The state parameter is required and may not be empty. Pass in nonsense text of at least one character if you don't care about validation
If your user is not logged in, they will be prompted by the website to log in. After successful login your user will be prompted to authorize your app to access their fitness data.
Assuming they trust you and authorize they will be redirected back to your app at the redirect_uri you specified, along with your authorization code and state provided in the URL parameters code and state.
Step 2: Obtain the access and refresh tokens from the API
With the authorization code you received you can now request an access token:
HTTP POST https://api.sporttracks.mobi/oauth2/token
HTTP Parameters:
- client_id - Your client id.
- client_secret - Your client secret.
- redirect_uri - Your redirect URI.
- grant_type - "authorization_code"
- code - The authorization code you received in Step 1.
HTTP Headers:
- Accept: "application/json"
- Content-Type: "application/json"
Step 3: Save your refresh token
If the POST above is successful, you'll receive the following in a JSON response:
- access_token - A short lived token you will use to access the data API for this session.
- refresh_token - A long lived token that allows you to gain access later.
- expires_in - Number of seconds the access_token is valid for.
Currently our access token lives for 2 hours. Refresh tokens are good for at least 90 days. If you're going to perform offline sync operations you'll want to save the refresh token in a database row associated with your user.
Step 4: Use the data API with your access token
Using the access token you received above, you're now able to read and write data to the user's account. For example, the URL below allows you to get a summary list of the most recent workouts:
HTTP GETP https://api.sporttracks.mobi/api/v2/fitnessActivities
HTTP Headers:
- Accept: application/json
- Authorization: Bearer {YOUR ACCESS TOKEN}
The fitnessActivities method will return a JSON response of the user's workouts. See the API documentation for details.
Continue to use the REST API with the access token.
Refreshing the access token
Some time later you'll probably want to access the user's data again. By this time, it's likely the access token has expired.
To gain access again you'll need to use the refresh token you saved in the database to request a new access token:
HTTP POST https://api.sporttracks.mobi/oauth2/token
HTTP Parameters:
- client_id - Your client id.
- client_secret - Your client secret.
- redirect_uri - Your redirect URI.
- grant_type - "refresh_token"
- refresh_token- The refresh token you read from the database for this user.
HTTP Headers:
- Accept: "application/json"
- Content-Type: "application/json"
Note that this method may or may not return a new refresh token. If it returns one which is different than your current refresh token, you should update the stored token in the database. If it doesn't return a refresh token, well... you can keep using the one you already have.
If your app is still authorized, proceed to Step 4 above to access the user's data with the access token you receive.
Error handling
All methods will return HTTP 2XX on success and 4XX on error.
Additionally you may find information in the JSON response error and error_description fields.