The SmartAPI offers various types of API credential to authenticate requests. If you are a SmartRecruiters customer, you can create, view and manage your API credentials in the Credential Manager.

API Key

The SmartRecruiter API key is a 32-characters string that can be generated by SmartRecruiters users with Administrator access.

Authentication using API key requires you to include the header X-SmartToken and provide your API key as the value when making the API request.

An example authentication of a request using API key would look like -H "X-SmartToken: DCRA1-d0b1128084fb427ea**************"

API Keys are easy to use and provide full access the key provider's resources in SmartRecruiters. So we recommend using API Key only if you are a:

• Customer testing out SmartAPIs or an application/integration build
• Partner testing out SmartAPIs or an application/integration build
• Customer building your own hiring solution

OAuth

SmartRecruiters also supports the use of OAuth credentials to authenticate requests. Specifically under the OAuth 2.0 authorization framework, we support the two following flows:

1. Client Credential
2. Authorization Code

Authentication to the API is performed via bearer auth which requires users to exchange the credential for an access token. When you are making the call, include the header Authorization and provide your access token as the value.

An example authentication of a request using OAuth would look like -H "Authorization: Bearer DCRA1-d5c77a928320f57ef60329e7****************"

Steps required to exchange for an access token are different between the two OAuth flows. Read onto the respective OAuth subsections below for more detail on the steps.

OAuth offers better security and control as the credential provider can define specific access scopes per credential that limits the API user access to the provider's SmartRecruiters resources. We recommend using OAuth if you are a:

• Customer building a customized hiring solution for your own organization
• Partner building a customized application/integration for a specific SmartRecruiters customer
• Partner building an application/integration and planned to distributed to all SmartRecruiters customers via the SmartRecruiters Marketplace.

📘

Which OAuth flows should you use?

Your choice of OAuth flow should depend on your hiring solution workflow and the nature of data you required.

The main difference between the Client Credential flow and the Authorization Code flow is that in the Client Credential flow, the resource owner assumes the holder of the client credential is trusted and that the credential holder will have access to the owner's resources at an organization level. Whereas in the Authorization Code flow, each user needs to review the data required and grant permission individually and that each authorization code only provides access to the resource respective user has access to in the organization.

Client Credential flow:

• Often requires no user or only an admin level user to provide permission
• Enable application to access data defined in the access scope (e.g. All user data in the organization)

Authorization Code flow:

• Always requires individual user to provide permission
• Enable application to access data the individual user has access to that is defined in the access scope (e.g. The user data of the individual who provided permission only)