Skip to content
Last updated

1. Create an Application

Prerequisites:

  • A BrightHR administrator account

To create an API application:

  1. Browse to API Management
  2. Under Create new application click Create
  3. Give your application a name and create it
  4. Under that application you just created, note the Client ID and then click Create Secret
  5. Copy the Client Secret

Important: Store your client secret securely. You will not be able to view it again after closing the dialog.

2. Obtain a Bearer Token

The API uses OAuth2 client credentials flow for authentication.

To make a request to the API, you will first need to obtain a bearer token by following these steps:

  1. Use the client id and secret from your application
  2. Make a POST request to https://login.brighthr.com/connect/token
  3. The request body must include:
    • grant_type: client_credentials
    • client_id: your client id
    • client_secret: your client secret
  4. The Content-Type must be application/x-www-form-urlencoded

Example Request

curl -X POST https://login.brighthr.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Example Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

Once you have the bearer token, include it in the Authorization header of every API request:

Authorization: Bearer YOUR_BEARER_TOKEN

A bearer token is valid for 1 hour. Once it expires, you will need to obtain a new token by repeating the authentication process. If you make a request with an expired token, you will receive a 401 error with the problem type TokenExpired.

3. Making Your First Request

Once you have a bearer token, you can make your first API request. The following example calls the List Employees endpoint, which returns a list of employees in your organisation.

Example Request

curl -X POST https://api.bright.hr/employees/v1/query \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN"

Example Response

{
  "items": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": {
        "givenName": "Jane",
        "familyName": "Smith"
      },
      "employment": {
        "jobTitle": "Software Engineer",
        "start": "2023-01-15",
        "end": null
      },
      "email": "jane.smith@example.com",
      "externalReference": null,
      "_metadata": {
        "isRegistered": true,
        "isTerminated": false
      }
    }
  ],
  "continuationToken": null
}