Note: The workflow outlined in this article to manage a Harvest API key is in beta. All organizations can create and manage Harvest API keys, but the process available to you might differ slightly from the one shown here. This updated workflow will be available to all organizations in the coming weeks.
Greenhouse Recruiting's Harvest API allows your team to grant your internal developers and third-party partners access to your jobs, candidates, interviews, and other data via API. An individual can access this data only with a Harvest API key. Managing permissions via the Harvest API key allows you to permit or deny access to each Harvest endpoint individually, so you can have more control over what data a developer or third-party partner can access from your Greenhouse Recruiting account.
Note: Harvest API keys created before January 18, 2017 have full permissions to all API endpoints that existed at that time, but any new API keys created after that date must explicitly be granted specific required endpoint permissions. For further instructions on authentication and the data available in the Harvest API, please visit our Developer Resource's site.
In this article we will cover how to:
Create New Harvest API Key
Click the Configure icon in the upper right-hand corner. Navigate to Dev Center on the left-hand panel. From the Dev Center page, click API Credential Management.
From the API Credential Management page, click Create New API key.
In the Create New Credential dialog box, make the following selections:
- API Type: Harvest
- Partner: If available, select the partner who has requested the Harvest API key. If the partner is not listed, leave this dropdown blank.
- Description: [Partner name] Harvest API Key
When finished, click Manage Permissions to generate the Harvest API key. If you selected a partner in the Partner dropdown list, the appropriate permissions are assigned to the API key automatically. If the partner was not available in the dropdown, you can add permissions to the key in a subsequent step.
In the subsequent dialog box, click Copy to save your API key to your clipboard. Store the API key in a secure location to provide to the partner. Click I have stored the API Key once you have copied and saved the key.
Note: You cannot access the full Harvest API key again after clicking I have stored the API Key. If you lose your API key and need to access it later, you must create a new API key, provide it to the integration partner, and then revoke access to the original key.
On the subsequent page, confirm the correct permissions are assigned to your new API key, or assign the permissions yourself by clicking the appropriate checkboxes. We recommend granting each key only the exact access it requires. You may need to work with your internal development team or integration partner to determine which endpoints you should select.
When you finish selecting the appropriate endpoints, click Save at the bottom of the page.
You have created a Harvest API key successfully! Provide the key to your internal development team or integration partner as appropriate.
Update an Existing Harvest API Key
Note: Making changes to the permissions of an API key that is in use may impact internal or third-party tools that rely on data called from the API. To avoid potential service disruptions, please check with your development team or integration partner before making changes to a key's permissions.
For security, we also highly recommend sending API keys using a public key or other secure messaging service, rather than copying keys to plain text emails.
To update an existing Harvest API key, begin by clicking the Configure icon in the upper right-hand corner. Navigate to Dev Center on the left-hand panel. From the Dev Center page, click API Credential Management.
From the API Credential Management page, locate the key you wish to edit. Hover your mouse over the key and click the edit icon inline with the key name.
On the subsequent page, make your edits (such as changing the name of the key in the Description field, or adjusting the key's permissions by adding or removing checkmarks from the Manage Permissions section). When finished, click Save at the bottom of the page.
Revoke or Re-enable Harvest API Key
To deactivate a Harvest API Key and revoke its access from all individuals with the key, begin by clicking the Configure icon in the upper right-hand corner. Navigate to Dev Center on the left-hand panel. From the Dev Center page, click API Credential Management.
From the API Credential Management page, locate the key you wish to revoke. Hover your mouse over the key and click the revoke icon inline with the key name.
Note: Revoking an API key immediately removes access to they key's endpoints for any users or integrations. Double-check the API key you are revoking to ensure it is not in active use.
In the subsequent dialog box, click OK to confirm your request to revoke the Harvest API key.
To re-enable a Harvest API key later, hover your mouse over the key and click the Re-enable icon inline with the key name.
In the subsequent dialog box, click OK to confirm your request to re-enable the Harvest API key.