---
updatedAt: 2026-07-23T19:15:43.000Z
agentTools:
  projectIndex: https://harvestdocs.greenhouse.io/llms.txt
---

# Authentication

This guide explains how to authenticate to the Greenhouse Harvest v3 API.

## Quick start

* Identify your integration type:
  * **Partner integrations**: Use the Authorization Code flow (see the [partner OAuth guide](https://harvestdocs.greenhouse.io/docs/harvest-partner-oauth)).
  * **Custom integrations**: Use the Client Credentials flow (steps below).
* Generate an access token.
* Call Harvest v3 endpoints with `Authorization: Bearer <<ACCESS_TOKEN>>`.

## Authentication methods by integration type

| Integration type     | Auth method                        | When to use                                                                    |
| -------------------- | ---------------------------------- | ------------------------------------------------------------------------------ |
| Partner integrations | OAuth 2.0 Authorization Code Grant | For Greenhouse partners integrating with mutual customers                      |
| Custom integrations  | OAuth 2.0 Client Credentials       | For a customer-built integration used only within their own Greenhouse account |

> **Note:** During the v1/v2 → v3 transition period, you may also be able to generate a JWT access token for v3 using existing credentials. See the `Transition period: v1/v2 to v3` section below.

## Custom integrations: OAuth 2.0 Client Credentials (step-by-step)

### Step 1: Create Harvest v3 OAuth credentials

1. In Greenhouse, open **API Credentials**.
2. Click **Create new API credentials**.
3. Select **Harvest V3 (OAuth)**.
4. Save the credential, then configure the scopes your integration needs.

You’ll receive a **Client ID** and a **Client Secret**. Keep your Client Secret confidential.

> Note: When generating a client credential, an integration service user (ISU) is automatically generated and associated with these credentials. If you would like to associate requests with a different user, please use the `sub` param when generating the token in step 2.

### Step 2: Generate an access token

Make a server-to-server `POST` request to the token endpoint.

* **Endpoint:** `https://auth.greenhouse.io/token` ([API reference](https://harvestdocs.greenhouse.io/reference/generate-token))
* **Authentication:** HTTP Basic using `<<CLIENT_ID>>:<<CLIENT_SECRET>>`
* **Body format:** `application/x-www-form-urlencoded`
* **Body parameters (URL-encoded):**
  * `grant_type=client_credentials`
  * `sub=<<USER_ID>>` (a Greenhouse `user_id` to identify the authorizing user)

About `sub`:

* `sub` should be the **numeric&#x20;**`user_id` of a user in the Greenhouse account.
* If you do not provide a `sub` the user associated with the request will be the ISU attached to the credentials in [Step 1: Create Harvest v3 OAuth credentials](https://harvestdocs.greenhouse.io/docs/authentication#step-1-create-harvest-v3-oauth-credentials)
* If you’re not sure what a user’s `user_id` is, open the user in the Greenhouse UI and use the numeric id from the URL.
* Use a user with the permissions your integration needs. For example, **all list endpoints require authorization by a Site Admin**. For partners see partner docs for details: [Step 7: Access the Harvest V3 API](https://harvestdocs.greenhouse.io/docs/harvest-partner-oauth#step-7-access-the-harvest-v3-api).

Example request (`curl`):

```bash
curl --location 'https://auth.greenhouse.io/token' \
  --user '<<CLIENT_ID>>:<<CLIENT_SECRET>>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials&sub=<<USER_ID>>'
```

Example response:

```json
{
  "token_type": "Bearer",
  "access_token": "received_access_token_string...",
  "expires_in": `integer_seconds_until_expiry...`
}
```

### Step 3: Call the Harvest v3 API

Use the returned token in the `Authorization` header:

```http
Authorization: Bearer <<ACCESS_TOKEN>>
```

Example request:

```bash
curl --location 'https://harvest.greenhouse.io/v3/job_posts' \
  --header 'Authorization: Bearer <<ACCESS_TOKEN>>'
```

### Step 4: Renew tokens

Access tokens expire. When you receive `401 Unauthorized` (or before expiration), request a new token by repeating Step 2.

## Partner integrations: OAuth 2.0 Authorization Code Grant (summary)

Partner integrations must use the OAuth 2.0 Authorization Code flow.

Full guide: [Integrating as a Greenhouse Harvest Partner (OAuth 2.0 Auth Code Grant Guide)](https://harvestdocs.greenhouse.io/docs/harvest-partner-oauth)

## Transition period: v1/v2 to v3

During the deprecation period, Greenhouse will support existing API credentials with the following methods:

* **Harvest v1/v2:** Basic authentication remains available.
* **Harvest v3:** Requires Bearer Authorization over HTTPS, using a valid JWT access token.

> **Important:** The token endpoints are different.
>
> * OAuth (custom integrations / partners): `https://auth.greenhouse.io/token`
> * Transition endpoint (generate access\_token): `https://harvest.greenhouse.io/auth/token`

Header examples:

```http
# v1/v2 (Basic)
Authorization: Basic <<base64_encoded_credentials>>

# v3 (Bearer)
Authorization: Bearer <<ACCESS_TOKEN>>
```

### Generating a JWT access token for v3 (during transition)

To generate a JWT access token for Harvest v3 during the transition period:

1. Obtain a Harvest API credential.
2. Use the `POST: generate access_token` endpoint: [API reference](https://harvestdocs.greenhouse.io/reference/post_auth-token)
3. Use the returned token as a Bearer token for `/v3` requests.

Example request (`curl`):

```bash
curl --location 'https://harvest.greenhouse.io/auth/token' \
  --user '<<V1_V2_HARVEST_API_KEY>>:'
```

Then, copy `access_token` from the response and use it as your Bearer token.

```http
Authorization: Bearer <<ACCESS_TOKEN>>
```

> **Important:** After v1 and v2 endpoints are deprecated, **OAuth will be the only supported authentication method** for the Harvest API. Transition early to avoid disruptions.

## Managing credentials (scopes, rotation, storage)

### Scopes

* **Custom integrations:** After creating **Harvest V3 (OAuth)** credentials, you can manage scopes in Greenhouse.
* **Partners:** Scope changes must be requested through Greenhouse Partner Support. See [Handling scope changes](https://harvestdocs.greenhouse.io/docs/handling-scope-changes).

### Secret rotation

When editing an API Credential, you can manually rotate secrets. After rotation:

* Old secrets are available for up to 1 week.
* You can delete the old secret ahead of the scheduled deletion if desired.

### Secure storage

* Store client secrets and tokens securely (server-side).
* Never store tokens/secrets in client-side code.

## Troubleshooting

* **401 Unauthorized**
  * Token expired/invalid. Generate a new token (custom integrations) or refresh it (partners; see [Step 6: Maintain Access (Refreshing the Access Token)](https://harvestdocs.greenhouse.io/docs/harvest-partner-oauth#step-6-maintain-access-refreshing-the-access-token)).
* **403 Forbidden**
  * The authorizing user may not have the required Greenhouse permissions.
  * Some endpoints (including all list endpoints) require a Site Admin authorizing user. See [Step 7: Access the Harvest V3 API](https://harvestdocs.greenhouse.io/docs/harvest-partner-oauth#step-7-access-the-harvest-v3-api).

<br />