Client Session ID Usage

The Client Session ID is a time-sensitive salt tied to the end-user's device and IP address. It is only needed if you are using Session Dropoff URLs to redirect users from your headless frontend to WordPress.

Enable Client Session IDs only if your application redirects users to WordPress-rendered pages:

• WordPress checkout page
• WooCommerce account pages
• Payment method management
• WooCommerce Subscriptions management

You do NOT need Client Session IDs if your application:

• Handles all checkout within the headless frontend
• Uses a payment gateway that doesn't require WordPress redirects
• Never redirects users to WordPress pages

Generate dropoff URLs client-side using the TokenManager and generateDropoffURL() function. This approach:

• Keeps nonce generation on the client
• Never exposes dropoff URL generation through your API
• Is the secure, recommended approach

WooGraphQL can expose session dropoff URL fields on the Customer type that you can query directly. However:

Warning: Querying dropoff URLs from the GraphQL API is highly insecure. It's strongly recommended to leave the session dropoff URL fields unregistered in the GraphQL API in production environments. Always use client-side generation instead.

Session Dropoff URLs contain a nonce that WordPress uses to validate the handoff request. The Client Session ID serves as part of the salt for generating these nonces, making them:

• Time-limited: Nonces expire after 1 hour
• Device-bound: Tied to the user's IP and User-Agent
• Single-use: Intended to be disposed of immediately after use

When SessionBehavior.withClientSession is enabled, the TokenManager generates a Client Session ID:

┌─────────────────────────────────────────────────────────────┐
│              createClientSessionId()                         │
├─────────────────────────────────────────────────────────────┤
│  1. Load or create client credentials:                      │
│     - User-Agent (from browser)                             │
│     - IP address (fetched from api.ipify.org)               │
│     - Issued timestamp                                      │
│     - Expiration timestamp (1 hour from now)                │
│                                                             │
│  2. Generate nonce hash from credentials                    │
│     (WordPress-compatible nonce algorithm)                  │
│                                                             │
│  3. Save to storage:                                        │
│     - Client Session ID                                     │
│     - Expiration timestamp                                  │
│                                                             │
│  4. Return { clientSessionId, timeout }                     │
└─────────────────────────────────────────────────────────────┘

After generation, the Client Session ID is sent to WordPress via the updateSession callback:

updateSession(tokens, {
  sessionData: [
    { key: 'client_session_id', value: clientSessionId },
    { key: 'client_session_id_expiration', value: timeout },
  ],
});

This stores the Client Session ID in the WooCommerce session meta. When a dropoff URL is accessed, WordPress uses the stored Client Session ID to verify the nonce.

When generating a dropoff URL, the Client Session ID is used as salt:

// The nonce is generated using:
// - User ID (from session token)
// - Client Session ID (device/time-bound)
// - Action type (cart, checkout, account, etc.)

const nonce = createNonce(action, userId, clientSessionId);
const url = `${wpUrl}/transfer-session?session_id=${userId}&${param}=${nonce}`;

Include SessionBehavior.withClientSession in your TokenManager configuration:

import { TokenManager, SessionBehavior } from '@woographql/session-utils';

const tokenManager = new TokenManager({
  ID: 'my-store',
  behavior: [
    SessionBehavior.withAuth,
    SessionBehavior.withClientSession, // Enable ONLY if using dropoff URLs
  ],
  startSession: async (tokens) => {
    // Fetch session token
  },
  updateSession: async (tokens, input) => {
    // Required for client session IDs - sends ID to WordPress
    const result = await graphqlClient.request(UpdateSessionDocument, {
      input: input.sessionData,
    });
    return result.updateSession.sessionToken;
  },
  // ...
});

The Client Session ID is automatically renewed every 45 minutes to ensure it stays valid while the user is active. This renewal:

1. Generates a new Client Session ID with updated credentials
2. Sends the new ID to WordPress via updateSession
3. Saves the updated session token

The Client Session ID is derived from "client credentials" - a combination of device identifiers:

These credentials are stored separately and refreshed every 14 days. The Client Session ID itself is regenerated every hour.

// Get the current client session ID
const clientSessionId = tokenManager.getClientSessionId();

if (clientSessionId) {
  // Use for session dropoff URL generation
  const checkoutUrl = generateDropoffURL(
    clientSessionId,
    userId,
    URLTypes.CheckoutPage
  );
}

The Client Session ID and its derived nonces have a 1-hour lifespan. This short window is intentional:

• Security: Limits exposure if a URL is intercepted
• Single-use intent: Dropoff URLs should be used immediately and disposed of
• Device binding: If user's IP changes, old nonces become invalid

If a user needs a new dropoff URL after the Client Session ID expires, the TokenManager automatically generates a new one during the next renewTokens() call.

• Session Dropoff URLs - How to generate and use dropoff URLs
• Session Behaviors - All available session behaviors
• Token Lifecycle - How Client Session ID fits in the renewal cycle