---
updatedAt: 2026-04-21T09:25:54.000Z
agentTools:
  projectIndex: https://docs.oysterhr.com/llms.txt
---

# Client credentials authorization

# Introduction

Oyster supports two OAuth 2.0 authorization grants: authorization code and client credentials. This guide covers how to use the client credentials authorization method. Access to client credentials is restricted, so if you would like to request access please contact <api-support@oysterhr.com>.

# When to use client credentials

Client credentials can be used when building an integration for internal company use or for certain partner use cases that don’t include customers enabling an integration in their account. [Listed integrations](https://docs.oysterhr.com/docs/integration-listing-instructions) can’t be authorized via client credentials since they require explicit user consent to be used by other companies.

# Requesting an access token

**Endpoint:** `POST https://api.oysterhr.com/oauth2/token`

**Content-Type:** `application/x-www-form-urlencoded`

**Body parameters:**

* `grant_type`: `client_credentials`
* `client_id`, `client_secret`: from the Developer application
* `scope`: space-separated scopes the Developer application is allowed to request (`read`, `manage` ,  `subscribe`)

**Example request (cURL):**

```bash
curl --location 'https://api.oysterhr.com/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=CLIENT_ID' \
  --data-urlencode 'client_secret=CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=read manage subscribe'
```

## Token response and lifetime

* Response includes **`access_token`**, **`token_type`** (Bearer), **`expires_in`**, **`scope`**, etc., consistent with other grants.
* **There is no `refresh_token`** for client credentials, so you must **obtain a new access token** after expiry - 2 hours.

# Endpoints requiring actor details

Certain endpoints require an actor to be specified. For these endpoints, you must use the `X-Oyster-Actor-Email` header. Check API reference to see if an endpoint requires `X-Oyster-Actor-Email`.

**Header name:** `X-Oyster-Actor-Email`

**Value:** Email address of a **User** with an Administrator role in the Oyster account