Humanity HVII Public API

Humanity Public API Developer Hub

Welcome to the Humanity Public API Developer Hub. You'll find comprehensive guides and documentation to help you start working with Humanity Public API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Getting Started with Authentication


Humanity v2 API uses OAuth2 for the authentication purposes. This section describes how an access token should be obtained for your Application (Client in OAuth2 terminology).

First of all, you need to create an API v2 application on Settings > API v2 page.

Generated App ID and App Secret values are necessary in further steps for getting the access token. Give a name to the application, and click Save. Redirect URI is not required.

Your application needs to use standard authorization code flow, as follows:

  1. Request authorization code by using POST method on:

With following parameters in body (x-www-form-urlencoded):

  • [client_id] - App ID of your API v2 application
  • [client_secret] - App Secret of your API v2 application
  • [grant_type] - 'password'
  • [username] - your username
  • [password] - your password
  • [redirect_uri] - Redirect URI of your API v2 application
Request example

Request example

  1. Response will be JSON encoded object, containing access token, refresh_token, expiration time in seconds, token type and scope. Here's an example:
    "access_token": "xxxxxxx",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "xxxxxxx"
  1. You can now use obtained access token to perform calls on the Humanity v2 API. Access token must be passed through the access_token query parameter on every API request.

Humanity v2 request example:

method: GET

You can find detailed documentation on our Humanity v2 API Reference page.

When your access_token expires, you authenticate with refresh_token the same way you obtain access_token, just change grant_type to refresh_token and send the refresh token in that request.