OAuth 2.0. Authorization Code grant

Making API requests on a user's behalf

Suggest Edits

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.

Authorization Code grant type suits better for partners who want to publish their applications on the SmartRecruiters platform.

This guide demonstrates the steps required to make an API request using OAuth Authorization Code grant.

1. Registering an application

Please follow the instructions on OAuth 2.0. Register an app page to register a new application and get the corresponding Client ID and Client secret credentials.

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 should construct a URL to the /identity/oauth/allow endpoint and redirect the user's client (usually browser) to it. On this page, the end-user can provide authorization to your app.

Below is an example of such constructed URL:

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: On this URI SmartRecruiters redirects the end-user after they authorized your application
  • scope: List of access scopes of your application. The access scope determines the number of end-user resources your application can access. While there is no limit on the number of scopes you can select per credentials, as best practice, we encourage you to only choose the required scopes following the principle of least privilege.
  • state: This is an optional parameter that can be used by your application to maintain the 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 agrees and clicks Authorize, SmartRecruiters will make a callback to your application and the end-user will be redirected to the redirect_uri your application had specified previously in the request to the authorization 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 and is unique per individual user. Please keep in mind that 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 authorization 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 query parameters like the example below shows:

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 you can find an example call to this 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 your 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. Please note that the access token has a limited lifetime. The expires_in indicates the duration in seconds when the token will be 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 request headers as Authorization: Bearer 'your-access-token-value' like the following example shows:

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 of a such call 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"
}

📘

Refresh token lifetime

Please note, that the lifetime of the refresh token is limited to 28 days and it can be used only once. You'll get another refresh token in the next successful authorization request.

Demo App

We prepared Passport — a demo app that showcases how to implement our OAuth 2.0 Authorization Code flow in Node.js. You can reuse it according to your needs.

Updated 10 months ago

What’s Next

Learn more about the different types of OAuth flows and access scopes