This API allows a B2B client to start a new onboarding session for a specific user under a specific integration. The API returns a generated onboarding link that can be delivered to the end user. The API is authenticated using an **OAuth 2.0 Client Credentials** access token.

For API reference documentation, refer to [Request New Onboarding for Integrations](https://developer.incode.com/reference/requestnewonboarding).

## Security Model  
The Request New Onboarding for Integrations API uses the **OAuth 2.0 Client Credentials** grant type — a server-to-server authentication pattern intended for trusted backend systems. Unlike the Authorization Code flow, this grant does not involve a user-facing login step. Instead, your server authenticates directly using a `client_id` and `client_secret` to obtain an access token, which is then used to authorize API requests.

A **Client Credentials integration** is created automatically for organizations that have **Integration Ecosystem** enabled.

## Find the Client ID & Client Secret  
To view the integration details in Dashboard:

1. In the left navigation, go to **Integrations**.
2. On the Custom tab, click **Default client credentials integration**.

3. Copy the Client ID to use in the [access token request](https://developer.incode.com/docs/null#step-1-obtain-an-access-token).
4. Click **Generate** to create the Client Secret. Copy it to use in the [access token request](https://developer.incode.com/docs/null#step-1-obtain-an-access-token). The secret is shown and copyable **only once**. Store it securely in a secrets manager or vault. If lost, you must generate a new one.

## Step 1: Obtain an Access Token  
Before calling the B2B onboarding endpoint, your backend must obtain a Bearer token from the Incode authorization server using the Client Credentials grant.

**Endpoint**: `POST {auth-server-url}/oauth2/token`

**Environment URLs**

| Environment | Auth Server URL |
| --- | --- |
| Demo | `https://auth.demo.incode.com` |
| SaaS / Production | `https://auth.incode.com` |

**Request Parameters**

| Parameter | Value | Notes |
| --- | --- | --- |
| `grant_type` | `client_credentials` |  |
| `client_id` | `{client_id}` | [Find the Client ID](https://developer.incode.com/docs/b2b-request-new-onboarding-api#find-the-client-id--client-secret) |
| `client_secret` | `{client_secret}` | [Generate the Client Secret](https://developer.incode.com/docs/b2b-request-new-onboarding-api#find-the-client-id--client-secret) |
| `scope` | `openid` |  |

**Example Request**

```undefined
POST {auth-server-url}/oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id={clientId}&client_secret={secret}&scope=openid
```

A successful response returns an `access_token` to be used as a Bearer token in Step 2.

## Step 2: Call the Request New Onboarding for Integrations Endpoint  
Use the access token obtained in Step 1 to call the onboarding endpoint.

**Endpoint**: `POST {base-api-url}/omni/b2b/onboarding/request-new`

**Environment URLs**

| Environment | Base API URL |
| --- | --- |
| Demo | `https://demo-api.incodesmile.com` |
| SaaS / Production | `https://saas-api.incodesmile.com` |

### Headers  
- `Authorization: Bearer <access_token>`
- `Content-Type: application/json`
- `x-api-key: {api_key}`

### Request Body  
| Field | Required | Description | Example |
| --- | --- | --- | --- |
| `integrationReference` | ✅ Yes | Unique identifier of the integration, as configured in Incode Dashboard. | `