This guide is designed for Customers who want to use the Oyster API to directly interact with your own company data on the Oyster platform. This guide will help you create a Developer App and authorize access on the Oyster API.

Create a Developer App

Oyster grants access to API resources based on OAuth2. To access the API, you must first create a Developer App.

You must have an account on Oyster to create a Developer App. You can create a Developer App in a Developer Sandbox for development purposes, and will need to then do the same in a production account before using the integration with your company data. You can find more information about requesting and using a Developer Sandbox in this guide.

Follow these steps:

1. Log in to your account.

2. Choose to create a new Oyster Developer App in the Developer Tab.

   

3. You will then be prompted to fill in the information about your developer application.

   1. Name is the application name.
   2. Description is an optional field and can be left blank.
   3. Redirect URL can be any publicly-accessible URL that can be viewed in a browser without redirecting. For example https://google.com. This must start with https.
   4. Choose the appropriate scopes for your application. Don’t include unnecessary scopes as this might discourage customers from authorizing your application.

4. Once submitted, you will see a popup with the Client ID and Client secret.

   1. The Client ID will still be available in the Developer applications list after you submit the page.
   2. Make sure to copy the Client secret before submitting the page as this will not be visible in plain text again! If you misplace the Client secret, you will be able to regenerate a new one in the Developer applications list.
   

Authorize access

If you’d like to use client credentials authorization flow, follow this guide. Otherwise, follow the instructions below.

Your developer app must be authorized to access any customer data. Authorization must be granted by a Company Admin via the Oyster application.

1. Click on the Authorization URL for your developer app (provided on the Developer Applications page).
2. In the new tab/window, authorize your Developer App to access your company’s data.
3. This will redirect your browser to the Redirect URL specified in your developer app (e.g. google.com).
4. The redirect will include a code parameter, which is the Authorization code required by the next step to request an Access Token. Make sure to copy this code. You don’t need anything more from that browser window, so you can close it.

Requesting an access token

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

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

Body parameters:

• client_id: your Developer app’s Client ID
• client_secret: you Developer app’s Client Secret
• grant_type: authorization_code
• code: the value of the authorization code from the previous step
• redirect_uri: the Redirect URL for your Developer app (must match exactly)

Example request (cURL):

curl --location '<https://api.oysterhr.com/oauth2/token>' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'client_id=Dgj0QXXXXXXXXXXXXXXAdvufsTVx8MUXTi4' \\
--data-urlencode 'client_secret=1234XXXXXXX' \\
--data-urlencode 'grant_type=authorization_code' \\
--data-urlencode 'code=qdWklbcj_7J2XXXXXXXXXXX_-NUEqxoxj3ARgdon3E' \\
--data-urlencode 'redirect_uri=https://partnerapp.com/dashboard/auth/oauth/return/AppXXXXXXXAPI/'

Example response:

{
    "access_token": "Kk71AT0LMa2-91pOQyw_mBvkKSAIJoeEUkIbTHQxYaI",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "VdWvQ9VgwV7Q2ipKXoXiOzUJQ-DStiwyP4rp8G5VEbI",
    "scope": "read",
    "created_at": 1688567808
}

The value of the access_token field is your Bearer Token. You must save the refresh_token for later use.

N.B. access tokens expire after 2 hours.

Refreshing an access token

An expired token cannot be reused, and a fresh token must be requested using the refresh token.

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

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

Body parameters:

• client_id: your Developer app’s Client ID
• client_secret: you Developer app’s Client Secret
• grant_type: refresh_token
• refresh_token: the value of the refresh token you saved previously

Example request (cURL):

curl --location '<https://api.oysterhr.com/oauth2/token>' \\
--header 'Content-Type: application/x-www-form-urlencoded' \\
--data-urlencode 'client_id=Dgj0QXXXXXXXXXXXXXXAdvufsTVx8MUXTi4' \\
--data-urlencode 'client_secret=1234XXXXXXX' \\
--data-urlencode 'grant_type=refresh_token' \\
--data-urlencode 'refresh_token=vxQ4Qdm7XXXXXXXXXXXXgQtZ1zEovgF_s'

The response will be a new access_token and a new refresh_token.