> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Greenhouse

## After this article

You will be able to connect Greenhouse to Lumos to sync users and their roles, and to suspend (de-provision) Greenhouse users from Lumos.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | No | User account records |
| Roles | Permission | Yes | No | Role definitions in Greenhouse |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Suspend | User | Suspends (disables) the user in Greenhouse |

## Required plan and roles

* **Greenhouse role:** the API key must be created by a user with **developer permissions** in Greenhouse (access to the Dev Center is required).
* **API key type:** a **Harvest** API key.
* **Key permissions:** grant the key the following Harvest permissions:
  * `GET: List Users`, `GET: Retrieve User` to sync user accounts
  * `GET: List User Roles`, `GET: List User Job Permissions` to sync role and permission assignments
  * `PATCH: Disable User`, `PATCH: Enable User`, `PATCH: Update a user` to suspend users during offboarding (and reverse it)
  * `POST: Add User`, `POST: Add User E-mail Address`
* **Permission scoping:** the `PATCH`/`POST` permissions let Lumos perform de-provisioning actions. For a sync-only setup you can't drop them from the documented permission set without breaking the connector's suspend capability.

## Read-only access vs provisioning

**Is read-only possible?** Yes. Harvest API key permissions are granted individually, so you can create the key with only the `GET` permissions and leave out the `PATCH`/`POST` permissions.

**What read-only requires.** A Harvest API key created by a user with developer permissions, with only `GET: List Users`, `GET: Retrieve User`, `GET: List User Roles`, and `GET: List User Job Permissions` selected. Follow the steps below, selecting only these permissions in the Create new credential dialog.

**What full provisioning requires.** The same Harvest API key with `PATCH: Disable User`, `PATCH: Enable User`, and `PATCH: Update a user` added, which power the Suspend deprovisioning action. The documented permission set also includes `POST: Add User` and `POST: Add User E-mail Address`, so select those too when you create the key.

**Watch out for.** Leaving out the `PATCH`/`POST` permissions breaks the Suspend action even though sync keeps working, so decide whether you need offboarding support before you create the key.

## Instructions

**Phase 1: Create a Harvest API key in Greenhouse**

1. Log in to your Greenhouse organization at [greenhouse.io/users/sign\_in](https://greenhouse.io/users/sign_in) as a user with developer permissions.
2. Click the **Configure** icon in the upper right-hand corner, then open **Dev Center** in the left-hand panel.
3. From Dev Center, click **API Credential Management**.
4. Click **Create New API key**. In the **Create new credential** dialog, give the key a name and select **Harvest** from the **Type** dropdown, then click **Create**.
5. Select the permissions listed in **Required plan and roles** above, then click **Update**.
6. Copy the API key.

**Phase 2: Connect in Lumos**

1. Find the Greenhouse card in your Lumos integrations (reconnect an existing card or add a new one).
2. **App Instance Identifier:** enter a unique identifier for this Greenhouse integration (for example `lumos-greenhouse-1`). This tells the integrations apart if you connect multiple Greenhouse instances.
3. Paste the API key.
4. Click **Connect**.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Connection fails with a valid key.** Confirm the key was created with type **Harvest** (not Job Board or Ingestion) and that all permissions listed above were selected before clicking **Update** in API Credential Management.

**Suspend actions fail while sync works.** The key is missing the `PATCH: Disable User` permission. Edit the credential in **Configure → Dev Center → API Credential Management** and add the missing permissions.

**Multiple Greenhouse instances conflict.** Each connected instance needs its own distinct **App Instance Identifier**. Reconnect the second instance with a different identifier.