OAuth 2.0

Overview

OAuth authentication is dedicated for productised apps, integration or connectors that are meant to be used by multiple SmartRecruiters users and made available in SmartRecruiters Marketplace. SmartRecruiters support the following OAuth 2.0 flows:

  1. Authorization Code – In this flow, end users will be asked to Sign In with SmartRecruiters credentials and to grant access to defined data within their account. 
  2. Client Credential – In this flow, defined data access is granted to trusted applications without the presence of end users.

Are you new to OAuth 2.0? Get started here.

Authorization Code flow

SmartRecruiters OAuth 2.0 Authorization Code flow implementation uses server-side flow which consists of the steps below.

Demo Apps

We’ve prepared Demo Apps that showcase how to implement our OAuth 2.0 Authorization Code flow in Java and Node.js. You can reuse it according to your needs.

1. Direct User to our authorization URL

The authorization process starts with your application sending a request to the SmartRecruiters authorization service.

Request

GET https://www.smartrecruiters.com/identity/oauth/allow

Path Parameters

name type description
client_id string Required. Client ID provided to you by SmartRecruiters when you register your application
redirect_uri string Required. The URI to redirect to after the user grants/denies permission. This URI should have been entered in the Redirect URI that you specified when you registered your application. The value of redirect_uri here must exactly match the values you entered when you registered your application, including upper/lowercase, terminating slashes, etc.
scope string Optional. A space-separated list of scopes: see Access Scopes for details. If no scopes are specified a default scope defined while creating an App is used
state string Optional. This is a value that can be used by the client to maintain state between the request and callback. SmartRecruiters as the authorizing server includes this value when redirecting the user back to the client.

Example Request

GET 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

2. User is asked to authorize your App to access their data

SmartRecruiters displays a page with details of the access scopes for which access is being sought. If User is not logged in, they are asked to do so using their SmartRecruiters credentials.

Users are asked to authorize access to data sets that have been defined in scopes.

3. User is redirected back to defined Redirect URI

Once a User authorizes your application (or denies), SmartRecruiters redirects them to a redirect_uri with a code or error parameter to be used in the next step.

If User has accepted your request, the response query string contains the following parameter:

name type description
code string An authorization code that can be exchanged for an access token
state string This parameter with the exact value received from the client will be included in the callback in cases where this parameter was provided in the authorization request.

Example Response

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

If User has declined your request or an error has occurred, the response query string contains the following parameters:

name type description
error string The reason authorization has failed
error_description  string  Description of an error
code  string  Error code

Example Response

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

You can find a full list of possible errors on the OAuth specification page.

4. Your App requests access_token

Now you need to exchange the code you have received in the previous step for an access_token. In order to make this exchange, you simply have to POST this code, along with some app identification parameters, to our access_token endpoint

POST https://www.smartrecruiters.com/identity/oauth/token

Form Parameters

name type description
grant_type string Required. Accepts the following values: authorization_code or refresh_token
code string Required. The exact code you received during the previous, authorization step
client_id string Required. Client ID provided to you by SmartRecruiters when you register your application
client_secret string Required. Client Secret provided to you by SmartRecruiters when you register your applicaiton

Example Request

curl --location --request POST 'https://www.smartrecruiters.com/identity/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'client_id=82e4424135fe01c169165228a84e7c5c' \
--data-urlencode 'client_secret=9165228a82e44244e7c5c8135fe01c16' \
--data-urlencode 'code=e63dfcab300260b2591f585126ede56627db4ef8'

Example Response

On success, the response from SmartRecruiters has the following JSON data in the response body:

{
   "token_type": "bearer",
   "access_token": "e7c5c8139165228a82e442445fe01c16",
   "expires_in": 3600,
   "refresh_token": "b2591f58e63dfcab3002605126ede56627db4ef8"
}
name type description
access_token string An access token that needs to be used to access Customer API endpoints
expires_in int The time period (in seconds) for which the access token is valid
refresh_token string A token that can be sent to the authorization service in place of an authorization code. (When the access code expires, send a POST request to the https://www.smartrecruiters.com/identity/oauth/token endpoint, but use this code in place of an authorization code. A new access token will be returned. A new refresh token might be returned too.)

Note: the code parameter expires after 30s so when executing curls manually might exceed the code’s lifetime. When this happens, you will receive an exception.

5. Use access_token to access the Customer API

The access_token allows you to make calls to Customer API endpoints on behalf of a user.

Example Request

curl -i -H "Authorization: Bearer e7c5c8139165228a82e442445fe01c16" -X GET https://api.smartrecruiters.com/candidates?status=New&status=Lead&tag=j2ee&tag=sql

6. Refresh your access_token

Access tokens are set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.

The request is sent to the token endpoint:

POST https://www.smartrecruiters.com/identity/oauth/token

Form Parameters

name type description
client_id string Required. Client ID provided to you by SmartRecruiters when you register your application
client_secret string Required. Client Secret provided to you by SmartRecruiters when you register your application
grant_type string Required. Set it to refresh_token
refresh_token string Required. The refresh token returned from the authorization code exchange

Example Request

curl --request POST \
--url 'https://www.smartrecruiters.com/identity/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "client_id=82e4424135fe01c169165228a84e7c5c" \
--data-urlencode "client_secret=9165228a82e44244e7c5c8135fe01c16" \
--data-urlencode "refresh_token=b2591f58e63dfcab3002605126ede56627db4ef8"

Example Response

On success, the response from SmartRecruiters has the following JSON data in the response body:

{
   "access_token": "e7c5c8139165228a82e442445fe01c16",
   "expires_in": 3600,
   "refresh_token": "0260b8e63dxcs32627db305126e2591f5de5b4ef8"
}
name type description
access_token string An access token that needs to be used to access Customer API endpoints
expires_in int The time period (in seconds) for which the access token is valid
refresh_token string The refresh token returned from the refresh code exchange

Client Credential flow

SmartRecruiters OAuth 2.0 Client Credential flow implementation uses mix of client-side and server-side flow which consists of the steps below.

1. Generating Client Credential

Navigate to the API Credential Manager under “Settings/Admins > Apps & Integrations > Credentials”. From the top right hand corner of the list, select ‘New credential” and choose ‘OAuth client ID’.

Defined the name, description and access scope of your new credential and complete this step with clicking ‘Generate’. You will see a pop-up screen displaying Client Id and Client Secret, this is your Client Credential and be sure to copy them before closing the pop-up.

You can find more detail on this step here

2. Requesting access_token

Similar to Authorization Code flow, you need to exchange the credential you have received in the previous step for an access_token. In order to make this exchange, you simply have to POST the client id-secret pair, along with some app identification parameters, to our access_token endpoint

POST https://www.smartrecruiters.com/identity/oauth/token

Form Parameters

name type description
grant_type string Required. Use the value: client_credentials
client_id string Required. Client Id you generated from the API Credential Manager in the previous step
client_secret string Required. Client Secret you generated from the API Credential Manager in the previous step

Example Request

curl -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
    -d 'client_id=82e4424135fe01c169165228a84e7c5c' \
    -d 'client_secret=9165228a82e44244e7c5c8135fe01c16' \
    -d 'grant_type=client_credentials' \
    -X POST https://www.smartrecruiters.com/identity/oauth/token

Example Response

On success, the response from SmartRecruiters has the following JSON data in the response body:

{
   "access_token": "e7c5c8139165228a82e442445fe01c16",
"token_type": "Bearer",    "expires_in": 1799 }

3. Use access_token to access the Customer API

The access_token allows you to make calls to Customer API endpoints.

Example Request

curl -i -H "Authorization: Bearer e7c5c8139165228a82e442445fe01c16" -X GET https://api.smartrecruiters.com/candidates?status=New&status=Lead&tag=j2ee&tag=sql

4. Refresh your access_token

Like Authorization Code flow, the access tokens are set to expire after a short time. However in the Client Credential flow, you can exchange for new access_token simply repeating step 2 again without the need of a refresh token.