In the Authorization Code flow, end users presence is required. The application utilizing Authorization Code needs to obtain permission and trust from individual end users.

This guides demonstrates the steps required to make an API requests using OAuth Authorization Code.

1. Registering an application

Submit a request to the SmartRecruiters team at [email protected] to register your application.

The SmartRecruiters team should provide you the Client ID and the Client secret for your application.

2. Obtaining an Authorization Code from an end user

2.1 Directing end users to the authorization URL

Once you have obtained the Client ID, your application can make a GET request the 'authorize' endpoint to direct the end user to a SmartRecruiters URL which the end user can provide authorization to your app.

Below is an example call to the 'authorize' endpoint:

curl https://www.smartrecruiters.com/identity/oauth/allow?client_id=82e4424135fe01c169165228a84e7c5c&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=candidates_read%20candidates_create%20candidates_offers_read

Notice different query parameters you should include in the request:

• client_id: The Client ID you obtained in step 1 from the SmartRecruiters support team.
• redirect_uri: The URI SmartRecruiters redirects the end user to after the end user authorized your application
• scope: List of access scopes of your application. The access scope determines the number end user's resources your application can access. While there is no limit on the number of scope you can select per credentials, as best practice, we encourage you to only choose the scope required following the principle of least privilege.
• state: This is an optional parameter which can be used by your application to maintain state between the request and the callback.

2.2 Obtaining permission from an end user

In the SmartRecruiters URL, the end user should see your application name and access scopes required from your application.

If the end user agreed and clicks 'Authorize', SmartRecruiters will make a callback to your application and the end user will be redirect to the redirect_uri your application had specified previously in the request to the 'authorize' endpoint along with the authorization code like the following example:

https://www.yourapp.com/callback?code=e63dfcab300260b2591f585126ede56627db4ef8

The code is the authorization code for your application an is unique per individual user. Do keep in mind the authorization code is short-lived and will expire after 30 seconds from the time your application received the code.

If the parameter state has been passed previously, the callback will include the exact value received from your application when your application made the request to the 'authorize' endpoint.

In the scenario where the end user clicks 'Decline' OR if an error occurred, the callback to your application will contain error and error description like the example below:

https://www.yourapp.com/callback?error=access_denied&error_description=The user denied access to your application&code=500

3. Exchanging for an access token

Once you obtained the Authorization Code, you will use it to exchange for an access token.

To make this exchange, you will need to make a POST request to SmartRecruiters 'access_token`'endpoint.

Below is an example call to the 'access_token' endpoint; the values of client_id and client_secret are the Client ID and Client secret you have obtained in step 1 and the value of code is the authorization code you application received in step 2:

curl https://api.smartrecruiters.com/identity/oauth/token \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d '{
    "client_id": "82e4424135fe01c169165228a84e7c5c",
    "client_secret": "9165228a82e44244e7c5c8135fe01c16",
    "code": "e63dfcab300260b2591f585126ede56627db4ef8",
    "grant_type": "authorization_code"
  }'

On success, you will receive the following response:

{
   "token_type": "bearer",
   "access_token": "e7c5c8139165228a82e442445fe01c16",
   "expires_in": 1799,
   "refresh_token": "b2591f58e63dfcab3002605126ede56627db4ef8"
}

The access_token is the OAuth access token you use to make API requests to SmartAPIs. Do note that the access token has a limited lifetime. The expires_in indicates the duration in second when the token will expired from the moment it was generated.

4. Making an API request

To make an API request to SmartAPIs, include the access token in the header of the request as Authorization: Bearer 'your-access-token-value' like the following example request:

curl -X POST "https://api.smartrecruiters.com/jobs" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer DCRA1-d5c77a928320f57ef60329e7****************" \
-d '{
    "firstname": "Susan",
    "lastname": "Santos", 
    "systemRole": {"id": "ADMINISTRATOR"}, 
    "language": {"code":"en"},
    "location": {"countryCode": "US", "city":"San Francisco"}
 }'

5. Refreshing an expired access token

Once an access_token expired, your application will need to use the corresponding refresh_token you have received in step 3 to make a request to the 'access_token' endpoint and exchange for a new access token.

Below is an example call to the 'access_token' endpoint with a refresh_token:

curl https://api.smartrecruiters.com/identity/oauth/token \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d '{
    "client_id": "82e4424135fe01c169165228a84e7c5c",
    "client_secret": "9165228a82e44244e7c5c8135fe01c16",
    "refresh_token": "b2591f58e63dfcab3002605126ede56627db4ef8",
    "grant_type": "refresh_token"
  }'

On success, you will receive the following response:

{
   "access_token": "e7c5c8139165228a82e442445fe01c16",
   "expires_in": 1799,
   "refresh_token": "0260b8e63dxcs32627db305126e2591f5de5b4ef8"
}