Client ID Management

Overview

Client IDs enable frontend/browser-side authentication with the Request Network API. Unlike API keys (which are for server-to-server calls), Client IDs are designed to be used in client-side code with domain restrictions. Key differences from API keys:

	API Key	Client ID
Use case	Backend integrations	Frontend/browser apps
Auth header	`x-api-key`	`x-client-id` + `Origin`
Domain restriction	None	Optional whitelist
Fee configuration	Per-request	Configurable per client ID

Backend vs Frontend Client IDs

Frontend Client IDs — have allowedDomains set. The API validates the Origin header against the whitelist.
Backend Client IDs — have empty allowedDomains. No domain validation is performed. Useful for server-side orchestrators that need client ID scoping without browser restrictions.

Orchestrator Pattern

When a Client ID is bound to a payee destination, requests created with that Client ID automatically resolve the payee from the destination. This enables orchestrator flows where a third party creates payment requests on behalf of a merchant without knowing the merchant’s wallet details.

Orchestrator (with Client ID) → POST /v2/request (no payee field)
  → API resolves payee from Client ID's bound destination
  → Payment goes to merchant's configured wallet

Two ways to manage Client IDs

Method	Best for
Dashboard (dashboard.request.network)	Most users — sign in with your wallet, generate a Client ID, set allowed domains, copy the value
Auth API (`POST /v1/client-ids`)	Automation, dynamic provisioning, multi-tenant orchestration

Both paths use the same Client ID — there is no functional difference.

CRUD Operations

Client IDs can be managed through the auth API (session-based) or the request API (API key-based).

Create a Client ID

curl -X POST "https://auth.request.network/v1/client-ids" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My Checkout Widget",
    "allowedDomains": ["https://mystore.com", "https://staging.mystore.com"],
    "payeeDestinationId": "0x6923...C7D7@eip155:8453#ABCD1234:0x8335...2913"
  }'

label

string

required

Display name for the Client ID (1-100 characters).

allowedDomains

string[]

List of allowed origins (max 10). Must be HTTPS, except http://localhost and http://127.0.0.1. Leave empty for backend Client IDs.

feePercentage

string

Default fee percentage for requests created with this Client ID (0-100).

feeAddress

string

Fee recipient address. Required when feePercentage is set.

payeeDestinationId

string

ERC-7828 destination ID to bind to this Client ID. Enables the orchestrator pattern.

operatorWalletAddress

string

Optional Ethereum address of a smart wallet with delegated operator permissions. Used in commerce payment (authorize/capture) flows.

defaultPreApprovalExpiry

number

Default pre-approval duration in seconds. Overrides per-request value when set.

defaultAuthorizationExpiry

number

Default authorization duration in seconds. Overrides per-request value when set.

Response (201)

{
  "id": "01HXEXAMPLE123",
  "clientId": "cli_abc123def456",
  "label": "My Checkout Widget",
  "allowedDomains": ["https://mystore.com", "https://staging.mystore.com"],
  "feePercentage": null,
  "feeAddress": null,
  "operatorWalletAddress": null,
  "defaultPreApprovalExpiry": null,
  "defaultAuthorizationExpiry": null,
  "payeeDestinationId": "0x6923...C7D7@eip155:8453#ABCD1234:0x8335...2913",
  "status": "active",
  "createdAt": "2026-03-15T10:00:00.000Z"
}

List Client IDs

curl -X GET "https://auth.request.network/v1/client-ids" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Get a Client ID

curl -X GET "https://auth.request.network/v1/client-ids/01HXEXAMPLE123" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Update a Client ID

curl -X PUT "https://auth.request.network/v1/client-ids/01HXEXAMPLE123" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowedDomains": ["https://mystore.com", "https://new-domain.com"],
    "label": "Updated Label"
  }'

All fields are optional. You can update label, allowedDomains, feePercentage, feeAddress, payeeDestinationId, operatorWalletAddress, defaultPreApprovalExpiry, defaultAuthorizationExpiry, and status.

Revoke a Client ID

curl -X DELETE "https://auth.request.network/v1/client-ids/01HXEXAMPLE123" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Revoking a Client ID is permanent and cannot be undone.

Webhook Scoping

Webhooks can be scoped to specific Client IDs. When a webhook is created with a clientId, it only receives events for requests created with that Client ID. See Webhooks for details.

Authentication

How to use Client IDs for API authentication.

Payee Destinations

Create destinations to bind to Client IDs.

🔑 API Setup

⚙️ API Features

📚 API Reference

Overview

Backend vs Frontend Client IDs

Orchestrator Pattern

Two ways to manage Client IDs

CRUD Operations

Create a Client ID

List Client IDs

Get a Client ID

Update a Client ID

Revoke a Client ID

Webhook Scoping

Authentication

Payee Destinations

​Overview

​Backend vs Frontend Client IDs

​Orchestrator Pattern

​Two ways to manage Client IDs

​CRUD Operations

​Create a Client ID

​List Client IDs

​Get a Client ID

​Update a Client ID

​Revoke a Client ID

​Webhook Scoping

​Related Pages

Authentication

Payee Destinations

Overview

Backend vs Frontend Client IDs

Orchestrator Pattern

Two ways to manage Client IDs

CRUD Operations

Create a Client ID

List Client IDs

Get a Client ID

Update a Client ID

Revoke a Client ID

Webhook Scoping

Related Pages