Skip to main content

Oauth 2.0

All endpoints for retrieving a CardioMood member's data require successful authorization via the OAuth 2.0 protocol. IETF RFC-6749 documents the full standard. While we will not explain OAuth 2.0 generally in this section, we will demonstrate how to use it to authorize an app's access to a CardioMood member's data after the member grants consent.

Any subsequent references to OAuth in this documentation will be referring to OAuth 2.0.

We recommend you use a library to manage the details of the OAuth flow. You can find recommended libraries in a variety of programming languages here.

Pre-requisite​

Before starting, you must create a Client App in the CardioMood Developer Dashboard. You can follow the getting started to learn how if you have not already.

Required Information for OAuth​

Client ID​

The client_id can be found after creating a client in the CardioMood Developer Dashboard.

Client Secret​

You can find the client_secret after creating a Client in the CardioMood Developer Dashboard.

Authorization URL​

This CardioMood URL prompts a user to authorize your app to access the CardioMood member's data. After the member grants authorization, CardioMood will respond with an authorization code.

https://api.health.cloud.cardiomood.com/oauth/authorize

Token URL​

This CardioMood URL provides your app with the authorization code from the authorization URL after the CardioMood member authorizes your app to access their CardioMood data. This endpoint provides an access token in exchange for the authorization code.

https://api.health.cloud.cardiomood.com/oauth/token

Response Type​

Parameter response_type should be equal to code

Redirect URI​

CardioMood will redirect the member to the Redirect URL after they authorize your App to access the request scopes. You must register the Redirect URL in the CardioMood Developer Dashboard.

A valid URL will take the form of https://cardiomood.com/example/redirect or cardiomood://example/redirect.

Note: Your OAuth library may reference Redirect URL as a Callback URL.

Example of Authorization URL​

https://api.health.cloud.cardiomood.com/oauth/authorize?client_id=63177104986024782d5bb7e2&redirect_uri=http%3A%2F%2Flocalhost%2Foauth-redirect&response_type=code

When user visits this address CardioMood will request from user permissions for your app to make requests on behalf of this user.

example

After user clicks Authorize button he or she will be redirected to redirect_uri passed in query parameters.

Parameter code will be passed in this redurect_uri.

Request An Access Token​

We highly recommend using a library to manage the flow. There are available libraries in many programming languages.

The steps that the library will follow are:

  1. Your application will send a request to the Authorization URL for an authorization code.
  2. CardioMood prompts the member to log in with their CardioMood credentials.
  3. The member will confirm they authorize access to your app.
  4. CardioMood will respond to the Redirect URL with an authorization code.
  5. Your application will send a request to the Token URL, exchanging the authorization code for an access token.

Sample POST Request Payload​

{
    "grant_type": "authorization_code",
    "client_id": "631XXXXXXXXXXbb7e2",
    "client_secret": "Vg78hYSECRETSECRETIxkhc",
    "redirect_uri": "http://localhost/oauth-redirect",
    "code": "def50200744cd95f2fa311ebd761f361d64d4144e250822d80db3d....."
}

Sample POST Response Payload​

{
   "token_type": "Bearer",
   "expires_in": 31536000,
   "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ....",
   "refresh_token": "def502009078aaf34f7d01c04d390c395089f...."
}

img

Using An Access Token​

After receiving an access token, all requests must include the access token. Your app should pass the access token as a Bearer token in the Authorization header.

CardioMood will return the requested data if the access token is successfully verified. However, if the token is invalid, CardioMood returns a 401 - Unauthorized response.

Access Token Expiration​

Access tokens are only valid for some time. CardioMood provides the token expiry in the expires_in parameter (in seconds). After the token expires, your app must refresh the token.

Refreshing an Access Token​

Access tokens are short-lived, depending on the expires_in value. CardioMood will respond with a (401 - Unauthorized) HTTP status code if your app sends a request with an expired access token.

When the access token is expired, you can no longer use it and must refresh the token. If you do not want to wait for the token to expire before refreshing, you can refresh the complete set of access tokens regularly. One strategy is to execute refreshing access tokens using a background cron job.

Existing access tokens are invalidated once your app uses the refresh token to generate a new access token. The access token from the refresh response is now the valid access token, and your app can use the new access token for future requests. Similarly, the refresh token from the refresh response is now the valid refresh token, and your app must use the new refresh token on the subsequent refresh request.

Another advantage to refreshing tokens in a recurring job is that it limits the likelihood of issues occurring with multiple concurrent requests attempting to refresh an expired token. When your app makes simultaneous refresh token requests, the first refresh request that reaches CardioMood will succeed. The second request would fail because the first request invalidates the refresh token.

CardioMood provides your app with a refresh_token after completing the OAuth 2.0 flow.

Required Information To Refresh​

Refresh Token Endpoint​

The CardioMood URL where your app sends a POST request including the refresh token in exchange for a new access token.

https://api.health.cloud.cardiomood.com/oauth/token

Refresh Token​

During the OAuth authorization flow, CardioMood returns a refresh_token that your app uses to refresh expired access tokens.

Client ID​

The Client ID is a unique identifier for your Client app. Your app uses this ID to authenticate with CardioMood. You can create and manage this ID in the CardioMood Developer Dashboard.

Client Secret​

The Client Secret is a secret value that accompanies a Client ID. You can view the Client Secret in the CardioMood Developer Dashboard.

Grant Type​

grant_type parameter should be equal to refresh_token

Sample POST Request Payload​

{
  "grant_type": "refresh_token",
  "client_id": "63177XXXXXXXXXXXX7e2",
  "client_secret": "Vg78hYA8ASECRETSECRET0oaIxkhc",
  "refresh_token": "def502009078aaf34f7d01c04d390c3..."
}

Sample POST Response Payload​

{
    "token_type": "Bearer",
    "expires_in": 31536000,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni....",
    "refresh_token": "def50200c027b235df5943950b5d52ff...."
}

img2

We prepared a tutorial for you how to use Oauth 2.0 with CardioMood.