Human API Developer Hub

Welcome to the Human API Developer Hub. You'll find comprehensive guides and documentation to help you start working with Human API as quickly as possible. Let's jump right in!

Get Started

Integrating Human Connect

Integrating Human Connect is easy. We have provided the code necessary to launch the popup and manage user interaction thereafter. For the integration, you will need to add the Connect Health Data button and manage callbacks from the popup.

Add the "Connect Health Data" Button

There are two steps to implement the Connect Health Data button:

1. Add our javascript library

This will create a global HumanConnect JS object.

<script src='https://connect.humanapi.co/connect.js'></script>

2. Add the button in the appropriate place on your page.

<img id='connect-health-data-btn' src='https://connect.humanapi.co/assets/button/blue.png'/>

Render the Connect Popup

Human Connect makes managing both new and returning users easy. When a user first connects, a user for your Human API app will be created with your specified clientUserId and you will be issued a publicToken as part of the auth process.

When a user returns to connect more sources or disconnect existing ones, simply include the publicToken to let them edit their connections.

Public Tokens

Make sure to hold on to that publicToken! You'll need it in order to render the Connect popup for returning users. Additionally, the publicToken changes each time the user connects a new source, so be sure to update it accordingly.

If the token goes missing, you can always get a new one with the publicTokens endpoint as detailed at the bottom of this page.

Launching the Human Connect Popup For New Users (Create Mode)

To launch Human Connect popup in create mode (when a user clicks on the connect health data button for the first time) you need to call the HumanConnect.open() function like so:

var options = {
  clientUserId: encodeURIComponent('UNIQUE_ID_FOR_YOUR_USER'), 
  clientId: 'CLIENT_ID', // grab it from app settings page
  publicToken: '',  // Leave blank for new users

  finish: function(err, sessionTokenObject) {
      /* Called after user finishes connecting their health data
       You need to post `sessionTokenObject` to your server to then:
       1. Append your `clientSecret` to it
       2. Send send it to our server for user credentials

       Sending a POST request with jQuery might look like this
      (it's not necessary to use jQuery):
      */
      $.post('/your-servers-endpoint', sessionTokenObject, function(res){

      });

      // Include code here to refresh the page.

  },
  close: function() {
      /* Optional callback called when a user closes the popup 
         without connecting any data sources */
  },
  error: function(err) {
      /* Optional callback called if an error occurs when loading
         the popup. */

      // `err` has fields: `code`, `message`, `detailedMessage`
  }  
}
HumanConnect.open(options);

The best practice for doing this is to call HumanConnect.open() inside the onClick handler for the connect-health-data-btn button we added earlier.

The specified options.finish callback will need to POST the sessionTokenObject to your server. To finalize the user authentication flow you will POST the sessionTokenObject signed with your clientSecret to our servers. Read more about this process below.

Refresh/Redirect on finish()

After you POST the sessionTokenObject to your server, you must redirect the user or refresh the current page with the publicToken data so that the Human Connect button will open in Edit Mode described below.

Human Connect will continue polling our servers after it is closed until you refresh the page. This is correct behavior and necessary for security reasons, despite a 412 response that may be seen in the javascript console.

Launching the Human Connect Popup For a Returning User (Edit Mode)

When an existing user clicks on the Connect Health Data button again, you will want to show them the sources they have already connected. To do this, you must pass the user's publicToken to HumanConnect.open in the options variable like so:

var options = {
  publicToken: 'PUBLIC_TOKEN_FOR_THE_USER', // you should have this from the successful authentication flow
 
  // Include the same code as launching Human Connect for a new user here 
  // (see above)
  } 
}
HumanConnect.open(options);

The remainder of the Human Connect authorization process remains the same. If the user adds or removes a source in edit mode, the finish() callback will be called and you will need to go through the same finalization process as detailed below in order to retrieve an updated accessToken and publicToken for the user.

User Already Exists Error

If you do not pass a publicToken upon launching Human Connect for an existing user, the user will see an User Already Exists Error and Human Connect will not launch properly.

Finalize User Authentication

Finalizing the authentication flow requires implementing a single server side endpoint. Lets walk through how to do it.

As we outlined in previous steps, after a user finishes connecting their health data through the Human Connect popup, you will get a sessionTokenObject with the following parameters:

{
  humanId: "52867cbede3155565f000a0d",
  clientId: "2e9574ecd415c99346879d07689ec1c732c11036",
  sessionToken: "8836c122c0483eb193ac2dd121136931"
}

You should send this token object from the client to your server as-is. On the server you need to add your clientSecret property to this object. This is done so that we can verify the request came from your application. You can find this value on your app settings page in the Developer Portal. A signed payload should look like this:

{
  humanId: "52867cbede3155565f000a0d",
  clientId: "2e9574ecd415c99346879d07689ec1c732c11036",
  clientSecret: "ee1551fb509598d0b656811633310889dc306aa3",
  sessionToken: "8836c122c0483eb193ac2dd121136931"
}

Now you can POST this signed object to the tokens endpoint below. Ensure that you set the Content-Type header to application/json.

https://user.humanapi.co/v1/connect/tokens

Here is an example of how you could do so in Node.js:

var request = require('request');

// common code for web app configuration should go here
// ...

app.post('/connect/finish', function(req, res) {
  var sessionTokenObject = req.body;
  // grab client secret from app settings page and `sign` `sessionTokenObject` with it.
  sessionTokenObject.clientSecret = '#CLIENT_SECRET';

  request({
    method: 'POST',
    uri: 'https://user.humanapi.co/v1/connect/tokens',
    json: sessionTokenObject
  }, function(err, resp, body) {
      if(err) return res.send(422);
      // at this point if request was successfull body object
      // will have `accessToken`, `publicToken` and `humanId` associated in it.
      // You should store these fields in your system in association to user's data.
      res.send(201);
    });
});

If the object was correctly sent you will get response like this:

{
  humanId: "52867cbede3155565f000a0d",
  accessToken: "95891f14f4bcpa23261987effc7cfac7fedf7330",
  publicToken: "2767d6oea95f4c3db8e8f3d0a1238302",
  clientId: "2e9574ecd415c99346879d07689ec1c732c11036",
  clientUserId: "user@yourdomain.com"
}
Property
Type
Description

humanId

String

A unique ID for the Human API user. Only useable by the application that registered the user.

accessToken

String

Unique token for the user. Used to query the user's health data. Should not be shared.

publicToken

String

Unique token for the user. Used to launch Human Connect popup in the edit mode. This token does not give access to user's health data through the API. To retrieve the publicToken for existing users follow the instructions at the bottom of this page.

clientId

String

Unique ID of the developer portal app you are working with.

clientUserId

String

Unique user ID passed into Human Connect during initial launch. Use this to associate the returned tokens with the appropriate local user.

You need to save humanId, accessToken, and publicToken somewhere in your system, and associate them with that particular user record.

User authentication via Human Connect is now complete! Utilize the accessToken to query the user's health data from Human API and don't forget to pass the publicToken to the Human Connect popup next time the user tries to add or remove a source. See the Customizing Human Connect page for info on customizing the language, color, and format of the Human Connect popup.

Read below for information on retrieving a publicToken for an existing user if needed.

Retrieve the publicToken for an Existing User

To retrieve the publicToken for a user, you need to post the humanId, clientId, and clientSecret to the publicTokens endpoint below. Ensure that you set the Content-Type header to application/json.

https://user.humanapi.co/v1/connect/publictokens

The payload will have the following properties:

{
  humanId: "52867cbede3155565f000a0d",
  clientId: "2e9574ecd415c99346879d07689ec1c732c11036",
  clientSecret: "ee1551fb509598d0b656811633310889dc306aa3"
}

The response to this query will have the humanId and the new publicToken

{
  humanId: "52867cbede3155565f000a0d",
  publicToken: "a95f4c3db8e8f3d0a1232767d6oe8399"
}

If you have troubles with our example or need recommendations on how to implement similar functionality using your language/framework, please let us know.

Integrating Human Connect


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.