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 = "";

// 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
    method: "POST",
    headers: {
        'Content-Type': 'application/json',
    body: JSON.stringify(requestBody)
.then(response => response.json())
.then(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
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

typeStringThe type of token you need. An "access" token or "client" token.
client_idStringYour client application identifier, provided to you by Human API
client_secretStringYour client application secret, provided to you by Human API
client_user_idStringYour unique identifier of the user (e.g. policy number). This is required only when “type=access”.

Common errors

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

errorCodeDescriptionHow to Fix
INVALID_TOKEN_TYPEThe specified token type parameter is invalidMake sure you are sending type: "session" or type: "id"
ACCESS_TOKEN_GENERATION_NOT_ALLOWEDUser is not allowed to generate access tokensThe end user must have connected an external account. If the user already connected a source and you are still receiving this error, please reach out to [email protected]
CLIENT_TOKEN_GENERATION_NOT_ALLOWEDclient_id is not allowed to generate client tokensReach out to us at [email protected]
INVALID_CLIENT_IDInvalid client_idMake sure that you are sending the correct client_id
INVALID_CLIENT_ID_OR_SECRETInvalid client_id or client_secretMake sure that you are sending the correct client_id and client_secret
UNKNOWN_CLIENT_USER_IDUnknown client_user_idWhen requesting type: "id", make sure that you have generated a session token for the user and that they have connected sources.
NOT_AUTHORIZEDNot authorized to perform this actionReach out to us at [email protected]