Swarm SDK

Turnstile Integration

This guide explains how Cloudflare Turnstile verification works with the Swarm SDK.

Overview

Cloudflare Turnstile is handled entirely by the SDK. No configuration or callbacks are required from the consuming application. The SDK automatically injects the Turnstile script, manages the widget lifecycle, and retries the original request on success.

Session Configuration

After connecting, the SDK receives Turnstile configuration from the server as part of the session handshake. The relevant fields forwarded to your onSessionSuccess callback are:

.ts
onSessionSuccess: (data) => {
  turnstile_enabled: true,
  turnstile_site_key: '0x4AAAAAAA...',
  turnstile_verify_actions: ['login', 'register_user', ...],
};

Field	Example value	Description
turnstile_enabled	true	Whether Turnstile verification is active on the server.
turnstile_site_key	"0x4AAAAAAA..."	The Cloudflare Turnstile site key used internally by the SDK.
turnstile_verify_actions	['login', ...]	List of command names that require Turnstile verification.

Trigger Scenarios

1. Pre-request check (action included in turnstile_verify_actions)

Before a request is sent to the server, the SDK checks whether the command is listed in turnstile_verify_actions.

The SDK calls window.turnstile.execute() silently in the background.
The SDK sends a Turnstile validation request to the server with the resulting token.
On success, the SDK sends the original request automatically.

2. Server-initiated (code 34 - TURNSTILE_VERIFICATION_REQUIRED)

The server may return response code 34 for a request that was not pre-checked, indicating Turnstile verification is required.

The SDK intercepts the response and calls window.turnstile.execute() silently.
The SDK sends a Turnstile validation request to the server with the resulting token.
On success, the SDK retries the original pending request automatically.

Error States

Scenario	Listener payload
turnstile_site_key missing from session	{ hasError: true, error: 'missing_turnstile_siteKey' }
Turnstile JS execution error	{ hasError: true, error: 'turnstile_execution_error' }