Authentication

Authenticate and authorize access to the SmartRecruiters APIs

The SmartRecruiters API Platform offers various ways to authenticate API requests. If you are a SmartRecruiters customer, you can create, view, and manage your API credentials in the Credential Manager. SmartRecruiters partners can register their own applications and make requests on a customer's behalf.

Every API published on this portal provides information about which authentication mechanism it supports. Consult the API Reference section or OpenAPI schema file directly.

Ways to authenticate

No authentication

Some APIs provide access to public data and don't require authentication by design. Examples of such APIs

Posting API

Common Endpoints

API Key

API key method gives your access to all company data and doesn't have scope or time restrictions. We recommend using this way for testing purposes only.

Read more about this authentication type in the API Key documentation.

Partner API Key

A similar mechanism to API Key but designed to be used by partners only. There are no new APIs planned to support this method and it's kept for legacy reasons.

Read more about Partner API Key.

OAuth 2.0 framework

SmartRecruiters supports user authentication and authorization via the OAuth 2.0 Authorization Framework. Particularly we use the next grant types in our APIs:

  1. Client Credentials grant
  2. Authorization Code grant

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

  • 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 distribute 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 the data you required.

The main difference between the Client Credentials 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 organizational level. Whereas in the Authorization Code flow, each user needs to review the data required and grant permission individually, and each authorization code only provides access to the resource the respective user has access to in the organization.

Client Credentials flow:

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

Authorization Code flow:

  • Always requires an individual user to provide permission
  • Enables 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)

Authentication methods comparison

Here you can find a comparison of all authentication methods available in SmartRecruiters APIs

MethodWhole organization dataRestricts access to data available to a userAccess Scopes support
API Keyβœ…βŒβŒ
OAuth 2.0 Client CredentialsOnly for credentials with the Admin role configuredβœ…βœ…
OAuth 2.0 Authorization CodeOnly for users with the Admin roleβœ…βœ…