How to start the development with Suunto Cloud API

1. Subscribe to the Developer API

To be able to use Integration API you have to subscribe to the API and add the subscription key to each request.

First, subscribe to the Developer API. You may change your subscription name. 

After completing the subscription you can find your subscription keys from your profile, under "Your subscriptions".

Both the primary key and secondary keys can be used with Integration API. The purpose of having 2 keys it to allow key regeneration and redeployment without app downtime. 

2. Configure your app/service in your profile

Setup the app information by editing the OAuth settings in the user profile.

Set at least:

  • App name

  • Client secret

  • Redirect URI

The Client Id is generating automatically.

3. Create a Suunto App user account for testing

Download and install Suunto App from Google Play or App Store and create an account with it.

You may synchronize data from your Suunto watch to your account, or track workout with the app itself to generate data you can test with.

4. Authorize the Suunto App user and obtain a JWT token

Authorization API has the address https://cloudapi-oauth.suunto.com.

You may call it from your browser or use the portal (browser window is preferred, as authorization process involves interaction with a user, which is not supported by the portal).

Replace <CLIENT_ID> and <REDIRECT_URI> in below URL using values in your OAuth application settings:
https://cloudapi-oauth.suunto.com/oauth/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>

Then, open the link to a browser, login using Suunto App credentials and authorize access for you app. 

You will be redirected to the provided REDIRECT_URI with an authorization code appended to query string parameter named 'code'.

For example, if the REDIRECT_URI was https://www.example.com/oauth-redirect, it'd look like this:

https://www.example.com/oauth-redirect?code=G5ahWs

Take the authorization code from the query string parameter and use it to obtain a JWT token. For example: 

curl -v https://cloudapi-oauth.suunto.com/oauth/token --user <CLIENT_ID>:<CLIENT_SECRET> -d grant_type=authorization_code -d redirect_uri=<REDIRECT_URI> -d code=<AUTHORIZATION_CODE>

Response:

{
  "access_token": "<JWT_TOKEN>",
  "token_type": "bearer",
  "refresh_token": "<JWT_REFRESH_TOKEN>",
  "expires_in": 86400,
  "scope": "workout"
}

Save the result for later use.

The access_token is a JWT token. You may parse it and extract a custom claim named 'user' which is the authorizing user's Suunto app account username. This username can be used later to find the access token for the specific user for example when handling a webhook notification about a new workout.

5. Try the integration API

The integration API has the address https://cloudapi.suunto.com. You may browse the APIs and try making request at the portal on the API -pages.

Making requests to the APIs requires using two HTTP headers:

  • Authorization - The JWT token from step 4.

  • Ocp-Apim-Subscription-Key - A subscription key from step 2.

For example you may try getting list of user's workouts with following request:

curl -v https://cloudapi.suunto.com/v2/workouts -h "Authorization <JWT_TOKEN>" -h "Ocp-Apim-Subscription-Key: <SUBSCRIPTION_KEY>"