Authorisation

All BrightHR APIs require your app to authorise using OAuth 2.0 access tokens.

The access token should be provided over HTTPS in every request as an authorization header, with the value of bearer <access_token>

Authorisation Types

Your app can be authorised in different ways, depending on the endpoint you`re interacting with:

• Personal Access Token
  For interacting with our APIs as yourself only.
• User Authorisation
  For interacting with our APIs on behalf of other users, using the OAuth 2.0 Authorisation Code grant with PKCE.
• App Authorisation
  For interacting with our APIs without any user context, using the OAuth 2.0 Client Credentials grant.

App Authorisation

This form of authorisation allows an app to make API requests on its own behalf (such as creating a company at `POST /v1/company`).

Access tokens issued with this method of authorisation do not include any user-context, therefore, requesting an endpoint which requires a user context with this token will produce a `403 Forbidden` response code. See our API Reference for the endpoints that are supported.

Apps require explicit approval by BrightHR before this type of authorisation method is available. Get in touch with us if you believe you have a requirement to use this.

Obtaining an App access token

You can generate an access token by passing your app`s Client ID and Client Secret to the token request endpoint detailed below.

• Sandbox - https://sandbox-login.brighthr.com/connect/token
• Production - https://login.brighthr.com/connect/token

TODO: [Detail request/response here for client credentials grant]

User Authorisation

This form of authorisation allows an app to make API requests on behalf of a BrightHR user. As part of the authentication flow, the user consents to your app accessing and/or modifying certain `scopes` of the user’s data. (This consent flow can be skipped for highly trusted internal apps).

Access tokens issued with this authorisation method contain an identifier for the user who authenticated, the access-level (scopes) they have provided to your app, and the permissions of the user in their company`s subscription. The access token can optionally contain user profile information if the correct scope is requested. See API Scopes for more details.

Obtaining a User access token

Most interaction with the BrightHR API require authorisation by a user. To get that authorisation, your app creates a request to the `authorize` endpoint, passing along a list of the scopes for which access permission is sought.

Personal Access Tokens

[TODO] Detail how PATs are long running and specific to the user

Scopes

Scopes are requested by a client app and are a way to segregate access to different categories of data.

OpenId Scopes

Requesting any of the following OpenId scopes results in the access token containing claims about the user.

• openid - This scope must be requested to identify the current user context. This results in a `sub` claim being included that contains their unique identifier.
• profile - Requesting this scope will include the following user claims: `given_name`, `family_name`, `job_title`, `picture`, `locale`, `zoneinfo`, `company_id`.
• email - Requesting this scope will include the user email address as the `email` claim.

API Scopes

Requesting any of the below API scopes results in the the user being prompted to consent to your app accessing that data on their behalf. Each scope represents a collection of available endpoints in our API. See the API reference for which scopes grant access to which endpoints.

• company:read
• employee:read
• employee:write
• subscription:write
• etc...