Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Ephemeral IDs

Ephemeral IDs are short-lived device identifiers that Turnstile generates for each visitor interaction. Unlike IP-based detection, Ephemeral IDs link visitor behavior to a specific client device without relying on cookies or client-side storage. This makes them effective against attackers who change IP addresses between requests.

How Ephemeral IDs work

Ephemeral IDs are dynamically generated for each Turnstile solve attempt. No cookies or local storage is required.

Ephemeral IDs are scoped to your Cloudflare account and cannot be shared across accounts. IDs expire within a few days and cannot be used to identify individual users.

This approach is particularly effective against credential stuffing and fake account creation attacks, where attackers rotate IP addresses to evade detection.

Refer to the blog post ↗ for more information.

Implementation

Enable Ephemeral IDs

  1. Contact your Cloudflare account team to enable Ephemeral ID entitlement for your account. This feature requires Enterprise-level access and cannot be self-activated.

  2. After entitlement is enabled, activate Ephemeral IDs for specific widgets using the Cloudflare API.

    cURL command
    curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$WIDGET_ID" \
      -H "Authorization: Bearer $API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "ephemeral_id": true
      }'

  3. Confirm Ephemeral IDs are active by checking your widget configuration.

    cURL command
    curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$WIDGET_ID" \
      -H "Authorization: Bearer $API_TOKEN"

Access Ephemeral IDs

Once enabled, Ephemeral IDs are included in Siteverify API responses.

Siteverify API response
{
  "success": true,
  "challenge_ts": "2022-02-28T15:14:30.096Z",
  "hostname": "example.com",
  "error-codes": [],
  "action": "login",
  "cdata": "sessionid-123456789",
  "metadata": {
    "ephemeral_id": "x:9f78e0ed210960d7693b167e"
  }
}

Availability

Ephemeral IDs are available to Enterprise Bot Management customers with the Enterprise Turnstile add-on or standalone Enterprise Turnstile customers. Contact your account team for access to Ephemeral IDs.