---
updatedAt: 2025-09-08T20:14:22.000Z
agentTools:
  projectIndex: https://platform.humanity.com/llms.txt
---

# Getting Started with Authentication

## Authentication

Humanity v2 API uses [OAuth2](http://oauth.net/2) 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.

![](https://files.readme.io/e1c4b79-Selection_555.png "Selection_555.png")

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

<Image title="Selection_296.png" alt={483} align="center" src="https://files.readme.io/b22f927-Selection_296.png">
  Request example
</Image>

2. Response will be JSON encoded object, containing *access token*, *refresh\_token*, expiration time in seconds, token type and scope. Here's an example:

```json Response example
{
    "access_token": "xxxxxxx",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "xxxxxxx"
}
```

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

```http v2
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](https://humanity-v2-publicapi.readme.io/v2.0/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.

![](https://files.readme.io/23e17b1-1c78484-Screenshot_2018-06-15_13-24-58.png "1c78484-Screenshot_2018-06-15_13-24-58.png")