> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshconnect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing sub-clients

By the end of this guide, you'll have sub-clients registered for your downstream merchants, with each user session applying the right per-merchant branding and compliance settings.

<Check>
  **Before you start**

  * You've confirmed with your Mesh representative that sub-clients are the right approach for your use case
  * Sub-client functionality has been enabled on your account
</Check>

## Overview

If Mesh is part of a product you offer to other businesses, sub-clients are how you represent each of your clients individually to Mesh. Each sub-client gets its own branding and compliance record, so the end-users of each merchant see an experience tailored to that merchant's product rather than yours.

This guide covers what sub-clients are, how to register them (via dashboard or API), and how to apply them to individual user sessions. For a concise introduction to the sub-client model, see [Concepts](/resources/concepts).

## What are Sub-Clients?

If your product is used directly by end-users, you can skip this guide. However, if your product is embedded within other platforms (e.g., you are a Payment Service Provider powering payments for multiple retailers), then sub-clients are critical. A Sub-Client represents the specific merchant or platform where your product is embedded, and where Mesh will be used. Registering them allows you to:

* **Ensure Consistent Branding:** Display the specific merchant's name and logo in the Mesh Link modal, creating a seamless experience for the end-user.
* **Maintain Compliance:** Mesh requires visibility into the legal entity associated with each transaction for compliance purposes.

## How to Register a Sub-Client

First, reach out to your Mesh representative to enable sub-client functionality for your account.

Then, you can register and manage sub-clients in two ways:

1. Manually, via the Mesh developer dashboard
2. Programmatically, via Mesh's Account Management API endpoints

### Option 1: Manually, via the Mesh developer dashboard

1. Navigate to **Account** > **Link Configuration** > **Clients** tab.
2. Click **"Add a client"**.
3. Enter the Business Legal Name, Display Name, Callback URL(s), and upload the relevant icon.
4. Click **Save**.

### Option 2: Via the Account Management API

For high-volume or automated setups, you can use a collection of Account Management API endpoints ([see here](https://docs.meshconnect.com/api-reference/account-management/registered-clients/add-new-registered-client)) to create, read, update, and delete sub-clients. To use this API, you must first generate a dedicated API key in the developer dashboard and configure security settings.

1. **Generate an API Key:**
   * Go to **Account** > **API Keys > Account management API keys**.
   * Click to generate a new key.
   * Use this key to authenticate your requests to the **`https://admin-api.meshconnect.com`** endpoints.
2. **Configure IP Whitelisting (Security Requirement):**
   * Just like calls to any production Mesh endpoint, access to these endpoints are restricted to pre-approved IP addresses.
   * Go to **Account > API keys > Access** and add the specific IP address ranges from which your servers will make API calls.

## How to use a sub-client in a user session

Once a sub-client is registered (via Dashboard or API), you will receive a unique `subClientId`. To apply the sub-client's branding and settings to a transaction, you will pass this ID in your Link Token request as shown below (payment example):

```bash theme={null}
curl --request POST \
  --url https://sandbox-integration-api.meshconnect.com/api/v1/linktoken \ // This is pointing to sandbox
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \ // Replace
  --header 'X-Client-Secret: YOUR_API_KEY' \ // Replace
  --data '
{
  "subClientId": "SUB_CLIENT_ID", // Replace (the unique identifier for this registered sub-client)
  "userId": "UNIQUE_USER_ID", // Replace
  "restrictMultipleAccounts": true,
  "transferOptions": {
    "transactionId": "UNIQUE_TRANSACTION_ID", // Replace
    "transferType": "payment",
    "isInclusiveFeeEnabled": false,
    "generatePayLink": false,
    "toAddresses": [ // Replace (example array below)
      {
        "networkId": "0291810a-5947-424d-9a59-e88bb33e999d", // Solana
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", // Ethereum
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "aa883b03-120d-477c-a588-37c2afd3ca71", // Base
        "symbol": "USDC", // Replace
        "address": "xxx", // Replace
        "amount": 99.99 // Replace
      },
      {
        "networkId": "03dee5da-7398-428f-9ec2-ab41bcb271da", // Bitcoin
        "symbol": "BTC", // Replace
        "address": "xxx", // Replace
        "amount": 0.00141, // Replace
        "displayAmountInFiat": 99.99 // Replace
      }
    ]
  }
}
'
```

## Test your implementation

Before going live, verify that sub-client branding and session routing are working end-to-end.

**What to test:**

* **Branding**: Launch a Link session using a Link Token that includes your `subClientId`. Confirm that Link displays the sub-client's logo and display name — not your top-level account's branding.
* **Fallback**: Launch a session *without* a `subClientId`. Confirm that the default top-level branding appears correctly.
* **API path** *(if applicable)*: Create a sub-client via the Account Management API and confirm you receive a valid `subClientId` before using it in a Link Token request.
* **Sandbox first**: Register a sub-client under your sandbox account and test with your sandbox credentials (`https://sandbox-integration-api.meshconnect.com`). Sandbox and production sub-client registrations are separate.

**If sub-client branding isn't appearing:** Double-check that the `subClientId` in your Link Token request exactly matches the ID returned when the sub-client was created. An incorrect or missing ID silently falls back to top-level branding.

## What's next

With sub-clients registered and `subClientId` flowing through your Link Token requests, the natural next steps are customizing the experience further and controlling which assets each merchant's users can access:

* [Polish the experience](/build/polish) — customize themes, embed vs. overlay behavior, and other presentation options across your sub-clients

***

<Accordion title="AI coding reference (llms.txt)">
  *AI coding reference — a compact summary of this page's APIs, parameters, and patterns for use by AI coding assistants (following the [llms.txt standard](https://llmstxt.org/)). Human readers can safely ignore this.*

  **llms.txt — Managing sub-clients**

  Register and manage sub-clients (child Mesh accounts) for B2B/PSP contexts where you serve multiple downstream merchants.

  **Register via Dashboard**: Account > Link Configuration > Clients > Add a client. Fields: Business Legal Name, Display Name, Callback URL(s), icon upload.

  **Register via API**: POST to Account Management API at `https://admin-api.meshconnect.com`. Requires separate Account Management API key (Dashboard: Account > API keys > Account management API keys) and IP allowlisting.

  **Apply to user session**: Pass `subClientId` in Link Token request body. Result: Link displays sub-client branding instead of top-level account branding.

  **Testing**: Register sandbox sub-clients separately from production. Use `https://sandbox-integration-api.meshconnect.com` for sandbox sessions.

  **Fallback**: Omitting `subClientId` or using incorrect value silently falls back to top-level branding — no error thrown.

  **Use case**: Required for PSPs/payment platforms serving multiple merchants. Single-product direct-to-consumer apps do not need sub-clients.

  **Link Token with `subClientId` — canonical request body** (payment example):

  ```bash theme={null}
  curl --request POST \
    --url https://sandbox-integration-api.meshconnect.com/api/v1/linktoken \ // This is pointing to sandbox
    --header 'Content-Type: application/json' \
    --header 'X-Client-Id: YOUR_CLIENT_ID' \ // Replace
    --header 'X-Client-Secret: YOUR_API_KEY' \ // Replace
    --data '
  {
    "subClientId": "SUB_CLIENT_ID", // Replace (the unique identifier for this registered sub-client)
    "userId": "UNIQUE_USER_ID", // Replace
    "restrictMultipleAccounts": true,
    "transferOptions": {
      "transactionId": "UNIQUE_TRANSACTION_ID", // Replace
      "transferType": "payment",
      "isInclusiveFeeEnabled": false,
      "generatePayLink": false,
      "toAddresses": [ // Replace (example array below)
        {
          "networkId": "0291810a-5947-424d-9a59-e88bb33e999d", // Solana
          "symbol": "USDC", // Replace
          "address": "xxx", // Replace
          "amount": 99.99 // Replace
        },
        {
          "networkId": "e3c7fdd8-b1fc-4e51-85ae-bb276e075611", // Ethereum
          "symbol": "USDC", // Replace
          "address": "xxx", // Replace
          "amount": 99.99 // Replace
        },
        {
          "networkId": "aa883b03-120d-477c-a588-37c2afd3ca71", // Base
          "symbol": "USDC", // Replace
          "address": "xxx", // Replace
          "amount": 99.99 // Replace
        },
        {
          "networkId": "03dee5da-7398-428f-9ec2-ab41bcb271da", // Bitcoin
          "symbol": "BTC", // Replace
          "address": "xxx", // Replace
          "amount": 0.00141, // Replace
          "displayAmountInFiat": 99.99 // Replace
        }
      ]
    }
  }
  '
  ```
</Accordion>