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:
- 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.
- 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.
- Java Demo App on GitHub
- Node.js (Passport) Demo on GitHub and on NPM
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://api.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://api.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": 1799,
"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://api.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://api.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://api.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": 1799,
"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://api.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://api.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.
Updated 9 months ago