# Getting Started

## 1. Create an Application

**Prerequisites:**

- A BrightHR administrator account


To create an API application:

1. Browse to [API Management](https://account.brighthr.com/manage-api)
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


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


```json
{
  "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](/problems#token-expired).

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


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

### Example Response


```json
{
  "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
}
```