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. Reason for this is that in OAuth flow users will be asked to Sign In with SmartRecruiters credentials and to grant an access to defined data within their account.

Are you new to OAuth 2.0? Get started here.

Demo Apps

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

Using the Server-side flow

SmartRecruiters OAuth 2.0 protocol implementation uses server-side flow which consists of the following steps.

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

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

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 -X POST -d "grant_type=authorization_code&client_id=82e4424135fe01c169165228a84e7c5c&client_secret=9165228a82e44244e7c5c8135fe01c16&code=e63dfcab300260b2591f585126ede56627db4ef8" https://www.smartrecruiters.com/identity/oauth/token

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

or

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

Example Response

{
   "access_token": "e7c5c8139165228a82e442445fe01c16",
   "expires_in": 3600,
   "refresh_token": "b2591f58e63dfcab3002605126ede56627db4ef8"
}

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 applicaiton
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 -H "Content-Type:application/x-www-form-urlencoded;charset=utf-8" \
    -F 'client_id=82e4424135fe01c169165228a84e7c5c' \
    -F 'client_secret=9165228a82e44244e7c5c8135fe01c16' \
    -F 'grant_type=refresh_token' \
    -F 'refresh_token=b2591f58e63dfcab3002605126ede56627db4ef8' \
    -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",
   "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