How to start the development with Suunto Cloud API

1. Configure your app/service in your profile

1.1. Setup the app information by editing the OAuth settings in the user profile.
1.2 Set the Application name, client secret and redirect information. ClientId is generating automatically.

 

1.3 Setup the URL for workouts / activity data notifications

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

2.1 Subscribe in Developer API in the page: "SUBSCRIBE"
2.2 You may change your subscription name.  
2.3 After subscription you can find your API Keys from your profile, under "Your subscriptions"
2.4 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. 

Note:
Production API subscriptions are reviewed by Suunto.
You will not get access to production prior acceptance by Suunto.

3. In order to do development, please create account to SuuntoApp

You can find the Suunto App in Apple Appstore and Google Play

3.1. Download & Install Suunto App
3.2 Create an account
3.3 Synch data from your Suunto watch to your account or track workout with the app itself

 

4. Try the authorisaton API [following step by step example]

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

You can 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).

4.1 Test the authorisation API
4.2. Call https://cloudapi-oauth.suunto.com/oauth/authorize?response_type=code&client_id=<your client id from profile/oauth settings>&redirect_uri=
4.3. Login using Suunto App credentials and authorize your app access 

4.4 You will be redirected to the redirect_uri provided and authorization code will be added to the redirect url.

4.5 Use code to obtain 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 from step 4.4>

4.6 Save JWT token information. In the the JWT token in the user field you will receive Suunto user name, which you can use later to handle notification about new user activities/workouts.

5. Try the integration API [following step by step example]

The API has the address: CloudAPI.Suunto.com

You can test the integration API from Integration page

5.1. Get the list of user workouts by calling "Get workouts list" endpoint (https://cloudapi.suunto.com/v2/workouts). Use access token from step 4.5 to fill Authorization header.

5.2. Get the fit file of the user by using same Authorization header as on the step 5.1 (or request new if it expired using refresh token) and 

"workoutKey" field from JSON received on step 5.1.

 

 

6. Try the notification API

In order to receive notification about new user activities/workouts developer should implement notification handler.

Suunto partner notification  service will call this handler with 2 parameters passed in the POST request (request encoding: application/x-www-form-urlencoded) username and workoutid.

Using username parameter you can find appropriate access token, obtained on step 4.5, to access user data (in a JWT token user name stores in the user field). The workoutid parameter can be used to obtain FIT file (see step 5.2).

6.1. Create endpoint to receive notification.

6.2. Setup the notification handler information by editing the OAuth settings in the user profile. We currently support Basic Http Authentication scheme for partner's notification handler and simple token-based authentication. If you choose to use Basic Http Authentication, please fill Notification Access Token (username) and  Notification Access Secret (secret) fields in the form. You also can set Notification Access Token field only and this token will be sent as Bearer token in the Authorization header to your notification handler.

6.3 Sync new workout with Suunto App

6.4 Your handler will receive notification. The new workout notifications are processed in order so processing time is depends on the system workload.