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

Finalizing 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 (for mobile SDKs, this is referred to as the authURL). 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 successful body object
      // will have `accessToken`, `publicToken` and `humanId` associated in it.
      // You probably want to store these fields in your system in association to user's data.
      res.send(201, body);
    });
});

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.

Also, see Customizing Human Connect page for info on customizing the language and format of the Human Connect popup.

When accessTokens and publicTokens refresh

As users connect additional data sources within Connect, the system triggers the finish callback and sends a new accessToken and publicToken for the user. These new tokens must be saved in your local user record.

As users disconnect sources within Connect, the scenario does not trigger the finish callback. The validity of the original accessToken and publicToken for the user is therefore maintained.

Retrieve the publicToken for an Existing User

In the event that you've forgotten to save a user's publicToken, you can retrieve it by POSTing the appropriate 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"
}

Finalizing User Authentication