OAuth - Client Credential

Making API requests with Client Credential

In the Client Credential flow, 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 an API requests using OAuth Client Credential.

1. Obtaining a Client Credential

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


You will need to define the Credential name, the Description and the Scope of your new Client Credential.

As best practices, we recommend you to 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 scope 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 scope. A key-value 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 Credential safe and secure

The Client Credential - consists of Client ID and Client secret that displayed on the pop-up will only be shown once. For security consideration, admins will not be able to retrieve or see the after the initial pop-up is closed.

We recommend the generator of the credential 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.

To make this exchange, you will need to make a POST request to SmartRecruiters 'access_token`'endpoint.

Below is an example call to the 'access_token' endpoint; the values of client_id and client_secret are the Client ID and Client secret you have 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'

On success, you will receive the following response:

  "access_token": "e7c5c8139165228a82e442445fe01c16",
  "token_type": "bearer",
  "expires_in": 1799

The access_token is the OAuth access token you use to make API requests to SmartAPIs. Do note that the access token has a limited lifetime. The expires_in indicates the duration in second when the token will expired from the moment it was generated.

3. Making an API request

To make an API request to SmartAPIs, include the access token in the header of the request as Authorization: Bearer 'your-access-token-value' like the following example request:

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 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.


What’s Next

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