Getting Started with Authentication

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:

Request authorization code by using POST method to:
https://www.humanity.com/oauth2/token.php

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

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"
}

You can now use obtained access token to perform calls on the Humanity v2 API. Access token must be passed with the access_token query parameter or in Authorization header as Bearer token on every API request.

Humanity v2 request example:

method: GET
URI: https://www.humanity.com/api/v2/employees/12345?access_token=xxxxxxx

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

When your accesstoken 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.