---
updatedAt: 2026-04-21T09:26:08.000Z
agentTools:
projectIndex: https://docs.oysterhr.com/llms.txt
---
# Customer guide to creating and authorizing a Developer Application
Customers can follow this guide to create their Developer Application
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](https://docs.oysterhr.com/docs/developer-sandbox).
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](https://docs.oysterhr.com/docs/client-credentials-authorization). 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 '' \\
--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:**
```json
{
"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 '' \\
--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`.