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 [email protected].

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 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):

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