Authentication

Quick start

• Identify your integration type:
  • Partner integrations: Use the Authorization Code flow (see the partner OAuth guide).
  • 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

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.

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)
• 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 user_id of a user in the Greenhouse account.
• 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 (otherwise you may receive 403 Forbidden). For partners see partner docs for details: Step 7: Access the Harvest V3 API.

Example request (curl):

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:

{
  "token_type": "Bearer",
  "access_token": "received_access_token_string...",
  "expires_at": "iso8601_datetime_string..."
}

Step 3: Call the Harvest v3 API

Use the returned token in the Authorization header:

Authorization: Bearer <<ACCESS_TOKEN>>

Example request:

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)

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:

# 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
3. Use the returned token as a Bearer token for /v3 requests.

Example request (curl):

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.

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.

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)).
• 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.