Retrieve User Access Token

Make sure you take a look at the Web Guide, and Start a user session in order to learn the steps that need to be taken to set up Human API Connect

Using an Access Token

When you want to query the user's health data, you must first get an access token.

🚧

An access token can only be retrieved if the user previously connected data sources and is still active (not deleted). If either of those two cases are not met, the request will be rejected. If that is the case, you will instead need to Start a user session

// This example contains a client secret in the server context. 
// DO NOT use your client secret in the browser!

// This example uses an open source request library to create requests
// You can replace it with your favorite request library
// Make sure to use the latest node version and [email protected] for this sample script to work
const fetch = require("node-fetch");

// Human API's authentication URL
const authUrl = "https://auth.humanapi.co/v1/connect/token";

// Payload you send to the server
const requestBody = {
  client_id: "--YOUR_CLIENT_ID--",
  client_user_id: "--YOUR_UNIQUE_IDENTIFIER--",
  client_secret: "--YOUR_CLIENT_SECRET--",
  type: "access" // replace this value with "access" or "id_token"
};

// Issue a POST call to Human API's authentication service
fetch(authUrl,{
    method: "POST",
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify(requestBody)
})
.then(response => response.json())
.then(accessTokenData => {
    console.log(accessTokenData);
})
.catch((error) => {
    console.error('Error:', error);
});

🚧

Do not ever send your client secret through the browser

Retrieving user data should not be done through the browser, it should be done via a server. Do not expose your users data by loading your client secret onto a web page.

A successful response to the request above will look like this:

{
    "access_token": "<your access token>",
    "expires_in": 86400,
    "token_type": "Bearer",
    "refresh_token": "atrt-zr5-gTJD8kWiwsNSWwhX2PhQA5-Rz0MpkCQVmdeDkZ3"
}

📘

What should I do with the refresh_token?

Refresh tokens are not actively used today in the API. Though this is the case, we still recommend that you store the refresh_token in your database in the event it is required in the future.

If you would like to request for a new access_token, you can re-send a POST request to our /token endpoint.

When you successfully retrieve the access token, you will use it to get the user's health data from our Data API Overview.

Health Intelligence Platform (HIP) access tokens

If your provisioned client app is configured with HIP, you must make a different call to retrieve access tokens.

POST /v1/admin/token HTTP/1.1
Host: auth.humanapi.co
Content-Type: application/json
Cache-Control: no-cache

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "client_user_id": "applicant_unique_id",
  "type" : "access"
}

A successful response to the request above should look like this:

{
    "access_token": "your-access-token",
    "expires_in": 86400,
    "token_type": "Bearer",
    "refresh_token": "Rz0MpkCQVmdeDkZ3"
}

Request attributes

Common errors

Here are some of the most common errors that can be seen when attempting to retrieve an access token: