Authentication

There are 2 ways to onboard a user to the Cardiogram platform through Cardiogram Connect. You can either:

1. Direct the user to Cardiogram Connect's OAuth url which allows them to consent to data sharing (Similar to the "Sign in with Google")

2. Create a new Cardiogram user through the API

User Authentication and Consent with OAuth 2

Data sharing through the OAuth2 flow allows the users explicitly choose to share data via a dialog that explains what they're sharing and with whom.

If you're creating a new user and sending them to Cardiogram to connect, then, as part of getting you set up, we'll check that correct language is in place for your company's terms of service, privacy policy, and user interface.

Implementation

To obtain the user's consent, send them to the auth URL with your client id:

https://cardiogr.am/auth?response_type=code&client_id=<YOUR_CLIENT_ID>

The user is then prompted to connect with their Cardiogram account and is then shown a dialog giving them the choice of whether to share their data.

If the user clicks on "Yes, Share my data," you'll receive an temporary auth code as a parameter to your redirect URI:

https://your.redirect.uri/cardiogram/callback?code=XXXXXXXXXX

As part of getting you onboarded, we will set up your redirect URI with you

The next step is then to exchange the temporary auth code for OAuth 2 access tokens that can be used in subsequent API calls.

Creating a new Cardiogram user via API

The alternative is to create a Cardiogram account on behalf of your user. To do this, you need a unique identifier used by your system and the users' email.

Implementation

Create a new Cardiogram User

POST https://cardiogr.am/heart/oauth/users/new

This method will create a new Cardiogram user

Headers

Name	Type	Description
Content-Type	string	application/x-www-form-urlencoded
Authorization	string	Basic Auth Basic <Base64-encoded client_id:client_secret>

Request Body

Name	Type	Description
email	string	Email address of the user [email protected]
memberId	string	Unique identifier with your system kai123

200

{
    userId: '1', // <String> Cardiogram User ID
    code: 'auth_code' // <String> Your `auth_code` used to exchange for auth tokens
}

401

Note that the Content-Type for authentication related endpoints isapplication/x-www-form-urlencoded as opposed to JSON.

Authorization is done via basic auth.

The next step is then to exchange the temporary auth code for OAuth 2 access tokens that can be used in subsequent API calls.

Exchanging an auth code for OAuth2 tokens

To exchange the auth code for access and refresh tokens, post to the /oauth/token URI.

Note that your OAuth2 library may abstract the below token exchange process, but if you need to implement it explicitly, then make an HTTP Post similar to the below:

Retrieve access and refresh tokens

POST https://cardiogr.am/heart/oauth/token

Headers

Name	Type	Description
Content-Type	string	application/x-www-form-urlencoded
Authorization	string	Basic Auth Basic <Base64-encoded client_id:client_secret>

Request Body

Name	Type	Description
code	string	Your auth_code from above auth_code
grant_type	string	authorization_code

200

{
    token_type: "bearer", // <String>
    access_token: "access_token", // <String>
    refresh_token: "refresh_token", // <String>
    expires_in: 1547163941452 // <Number>
}

401

You can now use the access_token on any of the following API endpoints on behalf of that particular user.