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.

11201120

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:
    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
483483

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 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 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.

770770