OAuth2 Authentication

OAuth2.0 Process

OAuth2.0 is an authentication method that allows JobAdder users to grant your application access to their account.

If you are only developing a solution for one client (building a careers page for an agency etc.), you may want to perform the OAuth2.0 process manually (with postman or a custom script) to obtain the access token and refresh token for the account. Once you’ve gotten the these credentials you can plug them into your application/server config file.

Things to Consider

Item	Description
Access Token	Has a lifetime of 60 minutes from created.
Refresh Token	Expires if unused for 2 weeks. Using it resets its 2 week inactivity expiration timer
Offline Access	A refresh token is provided only if offline_access scope is supplied.
Code	The code value expires in 5 minutes from its created time and can only be used once. Ideally after the redirect, the code is exchanged immediately by your application.
Redirect URI	Redirect URI should be in the list of Authorized Redirect URI of the API Application used.
JobAdder User Deletion	The user that granted access to your application via OAuth2 can be deleted at any time (due to resignation etc.) by an administrator on the account. Users that has granted your application and then removed / deleted at a later stage will return a invalid_grant / invalid_request error from the API when the refresh token is used, you’ll be required to handle this in your integration.
JobAdder account details	The instance and account from the token response identifies the JobAdder account that is associated with the token.

In common implementations, a scheduled task is used to obtain a new access token before it expires using the refresh token.

IMPORTANT: Please note that as the Refresh token is needed to request a new Access token, it is strongly recommended to store this somewhere after obtaining it.

Steps

1. Redirect the JobAdder user (admin user or user with Grant API Access) to your application’s authorization url e.g:

https://id.jobadder.com/connect/authorize?response_type=code&client_id={CLIENT_ID}&scope=read%20write%20offline_access&redirect_uri={REDIRECT_URI}

IMPORTANT: The read and write scopes are general scopes that have access to almost all GET , POST , PUT API endpoints. To limit your API access for security or privacy reasons, only specify the scopes of the API endpoints you will be using and do not use the general read and write scopes. 

2. The JobAdder user will be redirected to a JobAdder login screen and will be required to sign in and grant your application access to their account. The user will be redirected to the redirect uri specified in your authorization URL

IMPORTANT: JobAdder user (admin user or user with Grant API Access) will need to sign in ( do not confuse with using the JobAdder developer account user )

3. When redirected, a ‘code’ query parameter is appended to your authorized redirect URI, your application is required to extract the value from the code parameter to exchange this for an access token and refresh token.

{REDIRECT_URI}?code={CODE}

Example request to exchange the code value

curl -X POST \
  'https://id.jobadder.com/connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code={CODE}&redirect_uri={REDRECT_URI}&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'

Via Postman:

IMPORTANT: Token requests can only be done from the back end / server side. Make sure you are passing the parameters in the POST request body as x-www-form-urlencoded and added the header Content-Type: application/x-www-form-urlencoded. Redirect URI used must be the same as redirect URI used in the authorization url.

Example response

{
  "access_token":"{ACCESS_TOKEN}",
  "expires_in":3600,
  "token_type":"Bearer",
  "refresh_token":"{REFRESH_TOKEN}",
  "api":"{API_URL}",
  "instance":"{INSTANCE_ID}",
  "account":{ACCOUNT_NUMBER}
}

4. The access token has an expiry time of 60 minutes from the created time, you have the ability to get a new access token using the refresh token (if offline_access scope is used) provided in step 3.

Example request to get a new access token

curl -X POST \
  'https://id.jobadder.com/connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&refresh_token={REFRESH_TOKEN}'

via Postman:

Example response

{
  "id_token":"{ID_TOKEN}",
  "access_token":"{ACCESS_TOKEN}",
  "expires_in":3600,
  "token_type":"Bearer",
  "refresh_token":"{REFRESH_TOKEN}",
  "api":"{API_URL}",
  "instance":"{INSTANCE_ID}",
  "account":{ACCOUNT_NUMBER}
}