When integrating a new application with your BetterCloud instance, the overall installation process is consistent. However, each integration is different, and may require varying levels and types of authentication. This article provides instructions for configuring and collecting all the information you need in order to add the Greenhouse Recruiting integration in BetterCloud.
BetterCloud requires the following authentication type when integrating with Greenhouse Recruiting regardless of SKU:
In addition to generating a valid API key by following the steps in the "Authentication" section below, we want to highlight the "Admin Email" variable required.
- The "Admin Email" variable is required by Greenhouse in order to make any "write" request (aka POST / PATCH / DELETE / PUT).
- Whereas only a valid API key is required to make "read" requests
- Checkout this Greenhouse article under the section "Why is a Greenhouse user ID needed for API requests?" to learn more).
BetterCloud highly recommends you create a dedicated service account for the "Admin Email" variable, and use that service account to create the API key (we recommend the service account is granted the "Site Admin" role in Greenhouse so they can generate API keys)
As Greenhouse's article highlights, not using a dedicated service account can cause confusion when auditing Actions performed by BetterCloud in the future, as the Admin Email field is the user listed as the actor in their Change logIn addition, BetterCloud highlights this is because we've seen that it can sometimes be common practice to integrate Greenhouse to BetterCloud using an API key generated by one active user, and the Admin Email of another active user. This setup can cause breaking changes if the one or both of those users are offboarded in Greenhouse in the future. For this reason, BetterCloud highly recommends integrating Greenhouse by using a dedicated service account that is a Site Admin, and an API key generated from that service account. Please continue reading to be walked through the Integration process.
Authentication
When adding the Greenhouse Recruiting integration you must enter a API Token
Please Note: In order to enable the Greenhouse/BetterCloud integration, you will need the developer permission Can manage ALL organization’s API Credentials.
To generate an API token, please take the following steps within Greenhouse Recruiting:
In the Greenhouse Recruiting dashboard, click on the settings icon on the top right corner of the screen
Select 'Dev Center' from the left menu
Select 'API Credential Management'
Click on 'Create New API Key' button on the top of the screen
Enter a 'Description' for your API Key and select 'Harvest' from the 'Type' dropdown list
Copy the API Key
Check the required Permissions fields and then Update
(Note: Greenhouse recommends the ‘Departments’, ‘Jobs’, ‘Offices’, ‘User Roles’ and ‘Users’ fields. BetterCloud suggests Select All, to future-proof for new functionality.)
In your BetterCloud installation, enter a name for your installation in the field for 'Name'. Enter your Greenhouse API Key in the field for 'API Token'. Enter your email address (if you are the admin) in the field for 'adminEmail' then click install.
