Skip to main content

Authorization

Follow this guide to create a new Breezy HR credential that will allow Nexla to authenticate to and exchange data with your Breezy HR account.
breezy_hr_api_auth.png

Breezy HR

Prerequisites​

The Breezy HR REST API uses API key authentication. Each request to https://api.breezy.hr/v3 must include a valid API key in the Authorization header, and most endpoints are scoped to a specific company, so the company ID is also required when creating a credential in Nexla.

Before creating a credential, complete the steps below to generate an API key and locate the company ID for the Breezy HR company that will be connected.

Generate a Breezy HR API Key​

Breezy HR exposes API keys through the Integrations area of company settings. The signed-in user must have administrator access to the Breezy HR company in order to manage API keys.

  1. Sign in to your Breezy HR account at app.breezy.hr.

  2. Click the gear icon in the left sidebar to open Company Settings for the relevant company.

  3. Select Integrations from the settings menu.

  4. Scroll to the API section, and click Settings next to the API option.

  5. Click Generate API Key (or Create API Key) to generate a new key for this company. The key is displayed in full at the time of generation.

  6. Copy the generated API Key value, and store it securely. Breezy HR treats the API key as a bearer token equivalent to your account credentials, so it must be protected like a password.

    If an API key is exposed or needs to be rotated, return to the same API section under Integrations, and use the option to revoke the existing key and generate a new one. Any integrations using the previous key must be updated with the new value.

For complete information about API key generation and the authentication header format, see the Breezy HR Getting Started With Your API guide.

Locate the Breezy HR Company ID​

Most Breezy HR API endpoints are scoped to a specific company (positions, candidates, pipelines, questionnaires, and so on), so the Breezy HR Company ID must be supplied alongside the API key when creating a credential in Nexla.

  1. Sign in to the Breezy HR company that will be connected at app.breezy.hr.

  2. Use either of the following methods to obtain the company ID:

    Option A: Read the Company ID from the URL

    1. From the Breezy HR dashboard, navigate to any page scoped to the company (for example, Positions or Candidates).

    2. Inspect the browser address bar. The company ID is the segment that appears after /company/ in the URL (for example, https://app.breezy.hr/company/<COMPANY_ID>/positions).

    3. Copy the company ID value.

    Option B: Retrieve the Company ID via the API

    1. Issue a GET request to https://api.breezy.hr/v3/companies, supplying the API key generated above in the Authorization header.

    2. The response is an array of company objects. Locate the company that will be connected, and copy the _id field. This value is the Company ID used by all company-scoped endpoints.

  3. Store the Company ID value alongside the API Key for use when creating the credential.

Important

The Breezy HR API Key grants full programmatic access to the associated company's data, including the ability to create and modify positions and candidates. Store it in a secure secret manager, never commit it to source control, and rotate it immediately if you suspect it has been exposed.

Create a Breezy HR Credential​

  • To create a new Breezy HR credential, after selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

Credential Name & Description​

  1. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

    Resource descriptions are recommended but are not required. They should be used to provide information about the resource purpose, data freshness, etc. that can help the owner and other users efficiently understand and utilize the resource.

Authentication Settings​

  1. Enter the Breezy HR API key generated in the prerequisites in the API Key field. Nexla sends this value in the Authorization header on every API call to Breezy HR.

  2. Enter the Breezy HR Company ID located in the prerequisites in the Company ID field. Nexla substitutes this value into the /company/{company_id}/... path segment of every company-scoped API call. The Company ID is required because nearly every Breezy HR endpoint (positions, candidates, pipelines, questionnaires, custom attributes, assessments) is scoped to a single company.

    A credential connects to exactly one Breezy HR company. To integrate with multiple Breezy HR companies under the same account, create a separate credential for each company using the same API key (or a per-company API key) and the corresponding Company ID.

Save the Credential​

  1. Once all of the relevant steps in the above sections have been completed, click the Save button at the bottom of the overlay to save the configured credential.

  2. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation and can be selected for use with a new data source or destination.