Create an access token

Every request to the API is authenticated and authorized using a Bearer Token. The bearer token is an access token that you must generate using the Authorization Code from the previous step.

To create an Access Token:

Send a POST request to https://api.oysterhr.com/oauth2/token with the following form data:

For example, using 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/'

The response will look something like:

{
    "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.

To refresh an access token:

Send a POST request to https://api.oysterhr.com/oauth2/token with the following form data:

For example, using 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.