Client ID Management

Overview

Client IDs identify applications using the Request Network API. Domain-restricted Client IDs support frontend/browser integrations; Client IDs without allowed domains support server-side applications. Key differences from API keys:

	API Key	Client ID
Use case	Backend integrations	Frontend/browser or server-side applications
Auth header	`x-api-key`	`x-client-id` (plus `Origin` when domain-restricted)
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 applications that need Client ID scoping without browser restrictions.

Using a Client ID with a payment destination

When a Client ID is bound to a payee destination, a standard POST /v2/request call made with that Client ID can omit the payee. Request Network resolves it from the bound destination. This lets an application create requests without including wallet details each time.

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

This is separate from a formal orchestrator. For a Client ID linked to an orchestrator, creating a Secure Payment link or payout requires both x-client-id and x-orchestrator-key. A request using that linked Client ID alone is rejected. See paired authentication.

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 applications

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"
  }'

string

required

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

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.

string

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

string

Fee recipient address. Required when feePercentage is set.

string

ERC-7828 destination ID to bind to this Client ID. A standard Client-ID-authenticated request can then resolve its payee from this destination.

string

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

number

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

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

Using a Client ID with a payment destination

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

​Using a Client ID with a payment destination

​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

Using a Client ID with a payment destination

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