This guide describes how to set up the authorization code flow for your developer application. For information about using client credentials authorization, see this guide.

Authorize access

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

1. Copy the Authorization URL for your developer app (provided on the Developer Applications page) and save this as a configuration setting along with your Client ID and client Secret.
2. When a customer wishes to connect your application to Oyster, you will need to redirect the user to the Authorization URL to authorize your developer app.
   1. You can provide additional context to the Authorization URL using the state param. e.g. https://app.oysterhr.com/oauth/authorize/a1B2c3D4?state=yourInternalId. This param will be passed through verbatim and returned to you in the subsequent redirect.
3. Once the user has granted access to your developer app, they will be redirected back to the your application via the redirect URL.
4. The redirect will include a code parameter, which is the Authorization code required by the next step to create an Access Token.
   1. The redirect will also include the state param if you included it in the original authorization.
5. By default, apps can only be authorized by the company that created them. If you are a partner who would like to offer your app to other customers, please contact [email protected].

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.