---
updatedAt: 2025-09-24T09:13:05.000Z
agentTools:
  projectIndex: https://developers.smartrecruiters.com/llms.txt
---

# OAuth 2.0 General Partner Integration

Making API requests on a customer's behalf

# Connecting to SmartRecruiters

The SmartRecruiters – General Partner Integration follows the OAuth 2.0 protocol and utilizes the Client Credential flow to exchange data with integrating systems. We expect your team to be familiar with the OAuth 2.0 protocol. [OAuth 2.0 Client Credentials Grant ](https://oauth.net/2/grant-types/client-credentials/)document provides more information on OAuth 2.0 Client Credential flow.

Before customers can utilize your services within the SmartRecruiters platform, SmartRecruiters and your application will need to exchange credentials on two levels:

* **Partner Level (Master Credentials)** - credentials at this level are used to facilitate the customer-level credentials exchange during the integration setup process.
* **Customer Level** - credentials at this level are used:
  * By your application to access SmartRecruiters API on behalf of the customer
  * By SmartRecruiters to send requests to your application (in case of bi-directional integrations)

> 📘 Customer Level Credentials
>
> The term Customer-Level Credentials refers to credentials either generated by SmartRecruiters to access customer data or generated by your application.

<Image alt="General Partner Integration flow" align="center" width="65% " src="https://files.readme.io/821be83a0bf217a7f23b13ccb2679e6ed7a52e41cfd4e93297f4f96afe4d558f-image.png">
  General Partner Integration flow
</Image>

***

<br />

# 1. Obtain Partner-Level (Master) Credentials

Initial application setup is handled by the SmartRecruiters Partner & API Team. To issue a set of Master Credentials for your application, they will need the following information:

* **scopes** - access scopes that are required for your application. See [developer documentation](https://developers.smartrecruiters.com/docs/access-scopes) for the list of available scopes.
* **consentUrl**: The URL that SmartRecruiters will redirect the user to during the integration setup process. The user should authenticate and give their consent for the integration at the designated URL. SmartRecruiters will add `companyId` and `redirect` query parameters when redirecting user to this page.
* **consentDisplayMode**: This field determines the end-user experience during the integration activation step. There are two possible options:
  * **REDIRECT**: User will leave the SmartRecruiters integration setup page and will be redirected to the URL configured by the `consentUrl` field. SmartRecruiters will add the `redirect` query parameter in addition to `companyId`. The `redirect` parameter contains URL to redirect the user back to the SmartRecruiters when the credentials exchange process is complete.
  * **POPUP**: The user will stay on the SmartRecruiters integration setup page. The URL configured in the `consentUrl` will be used to display the pop-up iFrame widget.
* **oauthTokenUrl (optional)**: An endpoint defined by your application. SmartRecruiters will call this endpoint to get an OAuth 2.0 Bearer token. SmartRecruiters will use the customer-level credentials received from your application during the integration setup process. This token will be used by SmartRecuiters to access your API on behalf of the customer.
* **callbackUrl (optional)**: An endpoint for your application to receive `POST` requests with notifications on disabled integrations for a specific customer. Request will be signed with a Bearer token, exchanged from customer-level credentials at `oauthTokenUrl`. You can use the `clientId` associated with the token to identify the customer. `POST` body will contain the following object:

```
{
  "eventType": "INTEGRATION_DISABLED"
}
```

> 🚧
>
> Notifications to `callbackUrl` will not be send if `oauthTokenUrl` has not been defined.

* **logo**: The logo of your application, displayed on the Apps & Integrations page of the SmartRecruiters platform.
* **description**:  A description of your application, displayed on the Apps & Integrations page of the SmartRecruiters platform.

> 📘 Application's visibility
>
> If you use the General Partner Integration, your application will be displayed on the Apps & Integrations page of the SmartRecruiters platform. It can be made available to all customers or, if you're building a private integration, only to selected ones. You should confirm your application's visibility with the SmartRecruiters Partner & API Team.
>
> <Image alt="Applications that use General Partner Integration flow are presented on the Apps&Integrations page" align="center" src="https://files.readme.io/1ba462a42677b8a9d20282103ca0f064fbe618ce2930de7b50ca4bf9b7337710-image.png">
>   Applications that use General Partner Integration flow are presented on the Apps & Integrations page
> </Image>

<br />

After you have provided SmartRecruiters with the required data, our Partner & API Team will review the requested access scopes of your application. Once the review is completed, they will:

1. Approve your application’s access scopes, OR
2. Ask you to adjust requested access scopes based on the [Principle of Least Privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)

When the requested access scopes are approved, the Partner & API Team will also provide you with an **Application ID** and a set of **Partner Level Credentials (Master Credentials)**. The Master Credentials is a unique `clientId` and `clientSecret` pair for you to be able to access SmartRecruiters public API and setup integrations as requested by customers.

The SmartRecruiters Partner & API Team will share the Master Credentials with your team in an encrypted way.

<br />

# 2. Exchange Master Credentials for a Bearer Token

After you receive the master credentials, you can use them to obtain an OAuth 2.0 Bearer token, and use the token to finish setting up the integration requests from SmartRecruiters customers.

You can exchange your Master Credentials for an access token using the following endpoint:

```
https://api.smartrecruiters.com/identity/oauth/token
```

The token endpoint accepts the `POST` method. Below is an example request for exchanging the access token:

```
curl --request POST \
  --url 'https://api.smartrecruiters.com/identity/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET
```

<br />

# 3. Exchange Customer Level Credentials

When the customer initiates a connection from SmartRecruiters to your application, your predefined access scopes will be displayed on the integration setup page. Once the customer grants their permission, they are redirected to your platform. SmartRecuiters will use the `consentURL` you have provided in the previous step.

There are two front-end implementation options:

* SmartRecruiters provides a pop-up iFrame widget on the integration setup page to load your service sign-in page.
* SmartRecruiters redirect users to your sign-in page.

SmartRecruiters will add the following URL query parameters when making a GET request to the `consentUrl` page:

* **companyId** - a unique company identifier in SmartRecruiters
* **redirect** - URL to redirect user back to SmartRecruiters. Added only if you are using `consentDisplayMode=REDIRECT`. Your application should redirect users to the provided URL after the credentials exchange is completed.

Once the customer authenticates on your platform, your application must send a POST request to the following endpoint to confirm the integration:

```
https://api.smartrecruiters.com/apps-integrations/partner-api/integrations
```

Additionally, if the integration is bi-directional, the access scopes granted to SmartRecruiters should be displayed to the customer before their approval.

Request must contain your application ID and company ID. Furthermore, for bi-directional integration, you need to generate customer-level credentials to your API and send them to SmartRecruiters.

> 📘 Should you generate Customer Level Credentials for SmartRecruiters?
>
> Your application should generate Customer Level Credentials for SmartRecruiters and send them at this step if:
>
> * your integration is bi-directional, meaning you expect to receive API calls from SmartRecruiters while the integration is enabled
> * you want to be notified via a call to `callbackUrl` when a customer disables the integration on the SmartRecruiters side (in this case, you must also define `oauthTokenUrl`)

Request body example:

```
{
  "appId": "your-app-id",
  "companyId": "company-id-which-enables-integration",
  "clientId": "optional-client-id-to-your-api",
  "clientSecret": "optional-client-secret-to-your-api"
}
```

* **appId** - application ID provided to you by SmartRecruiters Partner & API Team in the previous step.
* **companyId** - a unique company identifier in SmartRecruiters, provided in the query parameter when redirecting user to the `consentUrl` page.
* **clientId** and **clientSecret** (required for bi-directional integrations) a set of customer-level credentials, generated by your application. SmartRecruiters will use it to sign requests to your API, e.g. to send you a notification about disabled integration or access the customer’s data.

> 🚧 ClientId uniqness
>
> Generated `clientId` you send in this step must be unique among all of your integrations.

When you make calls to the `/integrations` endpoint, you must include the master credentials Bearer token you obtained in the previous step in the `Authorization` header:

```
Authorization: Bearer cd251a04-4a00-4e7d-99e2-1b2e5431adb1
```

SmartRecruiters will return a `200 OK` response with customer-level credentials that you can use to access SmartRecruiters API and access customer data on behalf of the company.

Response example:

```
{
  "clientId": "string",
  "clientSecret": "string",
  "integrationId": "7cbc0f64-4d1c-4d70-9f19-dbd8f3656020"
}
```

> 📘 Not to be confused with the Master Credentials from the above sections
>
> This set of credentials is to access the given customer’s data via SmartRecruiters public API.

SmartRecruiters will generate a unique set of credentials for every company integration.

<br />

# 4. Finish the Integration Setup Process

Based on the value configured in `consentDisplayMode`, end-user experience at the last step may differ:

* **REDIRECT**: your application needs to handle the user frontend transition by sending users back to SmartRecruiters using the URL provided to you in the `redirect` parameter.
* **POPUP**: SmartRecruiters will handle the frontend user transition, closing the pop-up widget and refreshing the page.

At this point, the connection between SmartRecruiters and your application is set up for the specific customer. You can exchange credentials you received for the access token and use this token to access SmartRecruiters public APIs on behalf of the company you’re now integrated with.