> ## Documentation Index
> Fetch the complete documentation index at: https://requestnetwork-fix-req-350-remove-unused-webhook-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Client ID linking
> Link existing Client IDs or create them through platform onboarding so your orchestrator can create payment links, apply fees, and show its branding.
## Overview
Link a platform's [Client ID](/api-features/client-id-management) (`cli_*`) to your [orchestrator](/orchestrators/overview) to apply your [fees](/orchestrators/fees) and [branding](/orchestrators/whitelabel-branding). You can either link an existing client ID directly or create one through a hosted onboarding link.
All linking endpoints use the `x-orchestrator-key` header.
If you use hosted onboarding, [register an orchestrator webhook](/orchestrators/webhooks) before you send the onboarding URL. It receives the resulting client ID after the platform completes the flow.
A client ID can be linked to one orchestrator only. A second link request is rejected, whether it is for the same orchestrator or a different one. If you need to check whether a link request succeeded, list your linked client IDs instead of retrying it. Unlinking removes the active connection, but does not make the client ID linkable again.
## Link an existing client ID
Use direct linking only when the platform has shared an existing `cli_*` token with you:
```bash theme={null}
curl -X POST "https://api.request.network/v2/orchestrators/client-ids" \
-H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
-H "Content-Type: application/json" \
-d '{ "clientId": "cli_PLATFORM_CLIENT_ID" }'
```
On success, the response confirms an active link:
```json theme={null}
{
"link": {
"clientId": "cli_PLATFORM_CLIENT_ID",
"status": "active"
},
"alreadyLinked": false
}
```
The client ID must not already have a link record. A linked client ID can have client-specific orchestrator fee configurations; see [Orchestrator fees](/orchestrators/fees).
## Manage linked client IDs
### List linked client IDs
List active links with pagination:
```bash theme={null}
curl "https://api.request.network/v2/orchestrators/client-ids?page=1&limit=20" \
-H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"
```
The response returns active links and pagination details:
```json theme={null}
{
"links": [{ "clientId": "cli_PLATFORM_CLIENT_ID", "status": "active" }],
"total": 1,
"page": 1,
"limit": 20
}
```
### Unlink a client ID
To revoke an active link:
```bash theme={null}
curl -X DELETE "https://api.request.network/v2/orchestrators/client-ids/cli_PLATFORM_CLIENT_ID" \
-H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY"
```
Unlinking does not delete the client ID, but it removes the active association with your orchestrator. As noted above, it does not make that client ID linkable again.
## Onboard a platform with a link intent
Use a link intent when a platform should connect its own wallet, choose where it receives funds, and approve the connection to your orchestrator. The endpoint returns a hosted onboarding URL; send that URL to the platform.
```bash theme={null}
curl -X POST "https://api.request.network/v2/orchestrators/client-id-link-intents" \
-H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
-H "Content-Type: application/json" \
-d '{
"clientIdName": "Acme Store",
"domains": ["https://app.example.com"],
"externalId": "user_123"
}'
```
| Field | Required | Description |
| -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientIdName` | Yes | The name of the client ID created after the platform completes the hosted flow. |
| `domains` | No | Up to 10 unique allowed origins to copy to the new client ID. Each must be an HTTPS origin with no path, query, or fragment. HTTP is allowed only for `localhost`, `127.0.0.1`, or `[::1]` development origins. |
| `externalId` | No | Your correlation ID for the platform or onboarding session. Store it with the returned intent. |
| `kyt` | No | An orchestrator-controlled transaction-screening plan. Omit it to let the platform choose its screening preference. See [Orchestrator KYT plans](/orchestrators/kyt-plans). |
The response contains `url` and `intent`:
```json theme={null}
{
"url": "https://onboarding.request.network/?token=YOUR_ONBOARDING_TOKEN",
"intent": {
"id": "01JBQ8R2A6K3R7YJ8N6R4T7V9XF",
"clientIdName": "Acme Store",
"externalId": "user_123",
"used": false,
"expiresAt": "2026-08-15T10:00:00.000Z"
}
}
```
Store the intent ID, returned onboarding URL, and any `externalId` before sending the URL to the platform.
### What the platform does
The hosted flow asks the platform to:
1. Connect their wallet.
2. Create or update their active payment destination.
3. Review your screening plan, or choose a screening preference when you did not provide one.
4. Confirm the connection to your orchestrator.
After confirmation, Request Network creates a new `cli_*` client ID, copies any allowed domains from the intent, links it to your orchestrator, and binds it to the platform's active payment destination. Active orchestrator webhooks receive a [`client_id.linked` event](/orchestrators/webhooks) with the client ID, link identifiers, and destination details. Direct links do not send this event.
A link intent is single-use and expires after two days. Create a new intent if the platform has not completed the flow before it expires.
## Payment destination behavior
The client ID created through onboarding is bound to the payment destination selected in the hosted flow. When you create a secure payment link with that linked client ID, omit `destinationId` or provide that same destination. The API rejects a different destination ID.
The platform can manage its payment destination through the hosted flow; your orchestrator key does not choose it.
## Create payment links for a platform
To create a payment link for a platform, send both your orchestrator key and the platform's client ID.
After a client ID is linked, `x-client-id` alone cannot create a secure payment link. Use the same headers for incoming payment links and outgoing payout links.
These headers do not give you access to the platform's other client ID or account-management endpoints.
```bash theme={null}
curl -X POST "https://api.request.network/v2/secure-payments" \
-H "x-orchestrator-key: orc_YOUR_ORCHESTRATOR_KEY" \
-H "x-client-id: cli_LINKED_CLIENT_ID" \
-H "Content-Type: application/json" \
-d '{ "requests": [{ "amount": "100" }] }'
```
On success, the response includes the payment token and hosted payment URL:
```json theme={null}
{
"requestIds": ["01e273ecc29d4b526df3a0f1f05ffc59372af8752c2b678096e49ac270416a7cdb"],
"securePaymentUrl": "https://pay.request.network/?token=01ABC123DEF456GHI789JKL",
"token": "01ABC123DEF456GHI789JKL"
}
```
For an outgoing payout link, use the same headers with `POST /v2/secure-payments/payouts`.
The API validates that the client ID is active, linked to the orchestrator behind the supplied key, and has an active bound destination. This allows the payment link to use the platform's destination and your orchestrator configuration.
## Related
Apply fees and per-client-ID overrides to linked client IDs.
How platforms create and manage the `cli_*` client IDs you link.
Choose who controls transaction screening for hosted onboarding.