In the Client Credentials grant, an end-user presence is not required. An application that holds the credential is assumed to be authorized and trusted.

This guide demonstrates the steps required to make API requests using OAuth Client Credential.

1. Obtaining credentials

In SmartRecruiters Credential Manager, click the button New Credential and choose the option OAuth client ID.

You must define the Credential Name, Description, and Scope for your new Client Credential. Each generated credential is subject to the same authorization rules as all users on the SmartRecruiters platform. Therefore, a System role is required, while an Access Group is an optional attribute.

As the System role, you can choose from predefined roles or create a custom role. Note that even if the required OAuth scopes are selected, access to certain functionalities may still be restricted unless an appropriate System role is assigned.
For detailed information on setting up permissions, please refer to our Help Center.

As best practices, we recommend you provide a name and a description that help you and your admins to understand the function and purpose of the credential.

Your new Client Credential access to the API depends on the access scope you defined. While there is no limit on the number of scopes you can select per credentials, for security consideration, we encourage you to only choose the scope required following the principle of least privilege.

Click the Generate button on the bottom of the page once you defined the name, the description, and the scopes. A pair that consists of Client ID and Client secret will be displayed on a pop-up, this is your new Client Credential.

🚧

Keeping your Client Credentials safe and secure

The Client Credentials consist of Client ID and Client secret pair that is displayed in the pop-up only once. For security consideration, admins will not be able to retrieve or see it the after the pop-up is closed.

We recommend the generator of the credentials to keep these Client Credentials safe and secure.

2. Exchanging for an access token

Once you obtained the Client Credential, you will use it to exchange for an access token.

There are two methods to do it: client_secret_post and client_secret_basic method.

client_secret_post

To make this exchange, you will need to make a POST request to SmartRecruiters /identity/oauth/token endpoint.

Below is an example call to the access token endpoint with the values of client_id and client_secret obtained in Step 1:

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

client_secret_basic

To make this exchange, you will need to make a POST request to SmartRecruiters /identity/oauth/token endpoint. Below is an example call to the access token endpoint with example value of Authorization header:

curl https://api.smartrecruiters.com/identity/oauth/token \
  -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic AaNyc3BkNzZmZGNtczNiMjhtdGc6UjctX1ZOVEZQ1112WWxCbHFBVjdpUXhFLXVTQzBfWjFqWE1fZS0tOEZZas=' \
  -d 'grant_type=client_credentials'

The Authorization header must be in "Basic encodedString" format, where encodedString is a result of Base64 encoding of a string containing OAuth client's clientID and clientSecret, divided by the colon: clientID:clientSecret.

For both methods described above, on success, you will receive the following response:

{
  "access_token": "DCRD10-e7c5c8139165228a82e442445fe01c16",
  "token_type": "bearer",
  "expires_in": 1799
}

The access_token is the OAuth access token you use to make API requests to SmartRecruiters APIs. Please note that the access token has a limited lifetime. The expires_in indicates the duration in seconds when the token will expire from the moment it was generated.

3. Making an API request

To make a request to one of our APIs, you need to include the access token in the Authorization header of the request as 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"}
 }'

4. Exchanging for a new access token

In cases where your access token expired, you can simply repeat Step 2 using the same Client Credential and you should be able to obtain a new access token.

5. Revoking access

A Client Credential does not have an expiration date. However, in the scenario where a Client Credential is not used, lost, or suspected to be used maliciously by a third party, admins can revoke the Client Credential simply by clicking the Revoke button in Credential Manager.