DEV Community

Mike Anderson
Mike Anderson

Posted on

Using Cloudflare Turnstile Invisible Challenges for Mobile APIs Without Breaking the User Experience

Clouflare Turnstile

The problem we are solving

We have mobile apps calling APIs through Cloudflare. The APIs are seeing automated traffic from headless browsers, scripted clients, and bot-like agents. The business requirement is clear: reduce abuse without showing users a traditional CAPTCHA.

Cloudflare Turnstile can help, but the implementation has to be designed carefully.

The mistake is to treat Turnstile as something we send with every API request. That is not how Turnstile should be used. Turnstile produces short-lived, single-use tokens that must be validated by the backend through Cloudflare Siteverify. After validation, the application should issue its own short-lived clearance token and use that token for selected protected API calls.

The target design is:

Mobile app
  -> API request
  -> backend decides whether verification is needed
  -> if needed, return TURNSTILE_REQUIRED
  -> mobile app opens invisible Turnstile in WebView
  -> Cloudflare returns Turnstile token
  -> mobile app sends token to backend verification endpoint
  -> backend validates token with Cloudflare Siteverify
  -> backend issues scoped app_clearance_token
  -> mobile app retries the original API once
Enter fullscreen mode Exit fullscreen mode

This gives us bot friction without creating CAPTCHA friction for legitimate users.


Key design principle

Use Cloudflare Turnstile as a verification signal, not as your API authorization model.

Cloudflare Turnstile does this:

"This client passed a Turnstile challenge."
Enter fullscreen mode Exit fullscreen mode

Your backend still decides this:

"Should this API request be allowed, challenged, rate-limited, or denied?"
Enter fullscreen mode Exit fullscreen mode

That distinction matters. Cloudflare sees strong edge telemetry. Your backend sees the business context: user identity, device ID, failed login history, OTP velocity, payment behavior, endpoint sensitivity, and session state.

Cloudflare should be the edge enforcement and signal provider. The backend should make the final application risk decision.


What Cloudflare Turnstile keys mean

When we create a Turnstile widget, Cloudflare generates two keys:

Key Used by Security handling
Site key Frontend or mobile WebView challenge page Public identifier
Secret key Backend only Private credential

The site key is embedded in the Turnstile page. The secret key is used only by the backend when calling Cloudflare Siteverify.

Never put the secret key in:

mobile app code
frontend JavaScript
Git repositories
client-side configuration files
CI/CD logs
Enter fullscreen mode Exit fullscreen mode

Cloudflare documents that every Turnstile widget has a public sitekey and a private secret key, and that tokens must be validated server-side using Siteverify.


Recommended architecture

                         +----------------------+
                         | Cloudflare Turnstile |
                         +----------+-----------+
                                    |
                                    | token
                                    v
+------------+       +--------------+--------------+
| Mobile App | ----> | Mobile Turnstile WebView    |
+------------+       | /mobile-turnstile           |
       |             +-----------------------------+
       |
       | POST /api/security/turnstile/verify
       | turnstile_token + challenge_id
       v
+---------------------+
| Backend API         |
| - Siteverify call   |
| - risk decision     |
| - clearance token   |
+----------+----------+
           |
           | app_clearance_token
           v
+---------------------+
| Protected APIs      |
| X-App-Clearance     |
+---------------------+
Enter fullscreen mode Exit fullscreen mode

For native mobile applications, Turnstile does not run directly as a native SDK. It needs a browser environment. The practical pattern is to load a small Turnstile page inside a WebView. Cloudflare documents this WebView requirement for native mobile apps.


Step 1: Configure the Turnstile widget

In Cloudflare Turnstile:

Widget mode: Invisible
Hostname: hostname that serves the mobile Turnstile page
Enter fullscreen mode Exit fullscreen mode

Example hostname:

xyz@example.com
Enter fullscreen mode Exit fullscreen mode

Recommended challenge page:

https://xyz@example.com.dev/mobile-turnstile
Enter fullscreen mode Exit fullscreen mode

Add every hostname where the Turnstile widget will load. If the mobile app opens a WebView page from a dedicated hostname, that hostname must be included in Turnstile hostname management.

Keep pre-clearance disabled initially unless the WebView and native API client reliably share cookies and the API hostname is in the same Cloudflare zone. Cloudflare pre-clearance can issue a cf_clearance cookie, but mobile apps often use separate WebView and native HTTP client cookie stores.


Step 2: Build the mobile Turnstile page

This page loads Turnstile invisibly and passes the token back to the native app through a WebView bridge.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1"
  >
  <title>Security Verification</title>
  <script
    src="https://challenges.cloudflare.com/turnstile/v0/api.js"
    async
    defer>
  </script>
</head>
<body>
  <div
    class="cf-turnstile"
    data-sitekey="YOUR_TURNSTILE_SITE_KEY"
    data-size="invisible"
    data-callback="onTurnstileSuccess"
    data-error-callback="onTurnstileError"
    data-expired-callback="onTurnstileExpired">
  </div>

  <script>
    function sendToNativeApp(message) {
      const payload = JSON.stringify(message);

      if (window.AndroidBridge && typeof window.AndroidBridge.postMessage === "function") {
        window.AndroidBridge.postMessage(payload);
        return;
      }

      if (
        window.webkit &&
        window.webkit.messageHandlers &&
        window.webkit.messageHandlers.turnstile
      ) {
        window.webkit.messageHandlers.turnstile.postMessage(message);
      }
    }

    function onTurnstileSuccess(token) {
      sendToNativeApp({
        type: "TURNSTILE_SUCCESS",
        token: token
      });
    }

    function onTurnstileError(errorCode) {
      sendToNativeApp({
        type: "TURNSTILE_ERROR",
        error: String(errorCode || "unknown_error")
      });
    }

    function onTurnstileExpired() {
      sendToNativeApp({
        type: "TURNSTILE_EXPIRED"
      });
    }
  </script>
</body>
</html>
Enter fullscreen mode Exit fullscreen mode

Operational notes:

  • JavaScript must be enabled in the WebView.
  • DOM storage and standard browser APIs must be available.
  • The WebView page must be hosted on a hostname allowed in the Turnstile widget.
  • The site key is allowed in this page.
  • The secret key must never be included in this page.

Step 3: Create the backend verification endpoint

Create one endpoint for Turnstile verification:

POST /api/security/turnstile/verify
Enter fullscreen mode Exit fullscreen mode

The mobile app sends:

{
  "challenge_id": "chal_8f72a9c1",
  "turnstile_token": "TOKEN_FROM_WEBVIEW",
  "original_request_id": "req_12345",
  "device_id": "hashed-device-or-install-id",
  "app_version": "1.2.3"
}
Enter fullscreen mode Exit fullscreen mode

The backend calls Cloudflare Siteverify:

POST https://challenges.cloudflare.com/turnstile/v0/siteverify
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

Request body:

{
  "secret": "YOUR_TURNSTILE_SECRET_KEY",
  "response": "TOKEN_FROM_WEBVIEW",
  "remoteip": "CLIENT_IP",
  "idempotency_key": "8c0a8e9f-4f3b-4d72-8e3b-1c8e6b7d2e9a"
}
Enter fullscreen mode Exit fullscreen mode

Cloudflare Turnstile tokens are short-lived and single-use. Do not store the Turnstile token as a session token. Do not send the Turnstile token on every API request


Step 4: Use idempotency_key correctly

The idempotency_key is useful when the backend calls Siteverify and the request times out.

Without idempotency, this failure mode can happen:

1. Backend sends Turnstile token to Cloudflare Siteverify.
2. Cloudflare validates the token successfully.
3. Backend times out before receiving the response.
4. Backend retries Siteverify with the same Turnstile token.
5. Cloudflare may report the token as duplicate or already used.
6. A legitimate user can be incorrectly rejected.
Enter fullscreen mode Exit fullscreen mode

With idempotency:

1. Backend sends Turnstile token + idempotency_key.
2. Backend times out.
3. Backend retries with the same Turnstile token + same idempotency_key.
4. The retry is treated as the same validation attempt.
Enter fullscreen mode Exit fullscreen mode

Rules:

one challenge_id = one idempotency_key
reuse the same idempotency_key only for retrying the same Siteverify attempt
do not expose idempotency_key to the mobile app
expire the idempotency_key with the challenge, usually within 5 minutes
Enter fullscreen mode Exit fullscreen mode

Example Node.js verification function:

import crypto from "node:crypto";

export async function verifyTurnstile({
  challengeId,
  turnstileToken,
  clientIp,
  secretKey,
  challengeStore,
  siteverifyUrl = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
}) {
  const challenge = await challengeStore.get(challengeId);

  if (!challenge) {
    return { allowed: false, reason: "CHALLENGE_NOT_FOUND" };
  }

  if (challenge.used) {
    return { allowed: false, reason: "CHALLENGE_ALREADY_USED" };
  }

  if (Date.now() > challenge.expiresAt) {
    return { allowed: false, reason: "CHALLENGE_EXPIRED" };
  }

  let idempotencyKey = challenge.idempotencyKey;

  if (!idempotencyKey) {
    idempotencyKey = crypto.randomUUID();
    await challengeStore.update(challengeId, { idempotencyKey });
  }

  const body = {
    secret: secretKey,
    response: turnstileToken,
    remoteip: clientIp,
    idempotency_key: idempotencyKey
  };

  const response = await fetch(siteverifyUrl, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body),
    signal: AbortSignal.timeout(3000)
  });

  const result = await response.json();

  if (!response.ok || !result.success) {
    await challengeStore.recordFailure(challengeId, result["error-codes"] || []);
    return {
      allowed: false,
      reason: "SITEVERIFY_FAILED",
      errorCodes: result["error-codes"] || []
    };
  }

  await challengeStore.markUsed(challengeId);

  return {
    allowed: true,
    result
  };
}
Enter fullscreen mode Exit fullscreen mode

The example assumes the backend runs on a modern Node.js runtime where fetch and AbortSignal.timeout are available. If not, use the platform’s HTTP client and timeout mechanism.


Step 5: Issue your own app_clearance_token

After successful Siteverify validation, the backend should issue a short-lived application clearance token.

Example response:

{
  "app_clearance_token": "SIGNED_JWT_OR_OPAQUE_TOKEN",
  "expires_in": 900
}
Enter fullscreen mode Exit fullscreen mode

The mobile app then sends this token on selected protected APIs:

Authorization: Bearer USER_ACCESS_TOKEN
X-App-Clearance: SIGNED_JWT_OR_OPAQUE_TOKEN
Enter fullscreen mode Exit fullscreen mode

A good clearance token should include or reference:

user ID, when authenticated
device ID or installation ID
session ID
endpoint scope
risk level
issued_at
expires_at
max usage count for sensitive actions
challenge_id
Enter fullscreen mode Exit fullscreen mode

Example JWT-style payload:

{
  "sub": "user_123",
  "device_id": "hash_abc",
  "session_id": "sess_456",
  "scope": ["otp_request"],
  "risk_level": "medium",
  "iat": 1760000000,
  "exp": 1760000600,
  "max_uses": 1,
  "challenge_id": "chal_8f72a9c1"
}
Enter fullscreen mode Exit fullscreen mode

Suggested clearance lifetimes:

API category Clearance lifetime
OTP request or verification 5-10 minutes
Payment or checkout 5-10 minutes
Registration 10-15 minutes
Login 15 minutes
Search or scraping-sensitive APIs 15-30 minutes
Normal low-risk authenticated APIs Usually not required

Passing Turnstile once should not become a free pass. For OTP, payment, password reset, registration, and promo redemption, prefer single-purpose clearance tokens.


Step 6: Decide which APIs require clearance

Do not enable invisible Turnstile on every API call. It will create operational friction, more mobile failure modes, and unnecessary verification loops.

Start with endpoints that are attractive to attackers.

API type Example paths Why protect it
Login /api/auth/login Credential stuffing and password spraying
Registration /api/auth/register Fake account creation
OTP request /api/otp/request, /api/mfa/send SMS or email cost abuse
OTP verification /api/otp/verify Brute-force verification attempts
Forgot password /api/auth/forgot-password Enumeration and email bombing
Payment or checkout /api/payment/*, /api/checkout/* Fraud and card testing
Promo redemption /api/promo/redeem, /api/coupon/apply Automated abuse
Search or heavy query /api/search, /api/products/search Scraping and backend cost
GraphQL /api/graphql High-cost actions hidden behind one endpoint

Endpoints that usually should not require Turnstile at first:

API type Example paths Recommended control
Health checks /health, /ready No Turnstile
App configuration /api/app-config, /api/version No Turnstile unless abused
Public content reads /api/content, /api/catalog Rate limit first
Normal profile reads /api/user/me Usually no Turnstile
Telemetry /api/events, /api/analytics Schema validation and rate limits
Backend-to-backend APIs internal service calls mTLS or service authentication

A practical first policy:

turnstile_policy:
  always_require_clearance:
    - /api/auth/register
    - /api/otp/request
    - /api/otp/verify
    - /api/payment/*
    - /api/promo/redeem

  risk_based:
    - /api/auth/login
    - /api/auth/forgot-password
    - /api/search
    - /api/graphql

  never_require_clearance:
    - /health
    - /ready
    - /api/app-config
    - /api/version
Enter fullscreen mode Exit fullscreen mode

Step 7: Bound the retry loop

The mobile app must not loop forever.

Allowed flow:

API returns TURNSTILE_REQUIRED
  -> app opens invisible Turnstile WebView
  -> app receives Turnstile token
  -> app sends token to verification endpoint
  -> backend issues app_clearance_token
  -> app retries original API once
  -> if TURNSTILE_REQUIRED appears again, stop
Enter fullscreen mode Exit fullscreen mode

Not allowed:

API -> TURNSTILE_REQUIRED -> WebView -> verify -> retry -> TURNSTILE_REQUIRED -> WebView -> verify -> retry forever
Enter fullscreen mode Exit fullscreen mode

Backend-enforced limits:

Control Suggested limit
Automatic retry after clearance 1 retry per original request
Turnstile verification attempts 3 per 15 minutes per device/IP
Failed Siteverify responses 5 per 15 minutes per device/IP
Clearance token issuance 3 per 15 minutes per device/IP
OTP requests after clearance 1-3 per 10 minutes per phone/user
Login attempts after clearance 5-10 per 15 minutes per account/device
Same original request replay Block duplicate request ID

When limits are exceeded, return a clean response:

{
  "error": "SECURITY_VERIFICATION_LIMITED",
  "retry_after_seconds": 900
}
Enter fullscreen mode Exit fullscreen mode

Do not return detailed internal reasons such as bad-token, duplicate-token, or bot-detected to the client. Log those details server-side.


Step 8: Use a one-time challenge_id

When the backend decides Turnstile is required, return a one-time challenge transaction ID:

{
  "error": "TURNSTILE_REQUIRED",
  "challenge_id": "chal_8f72a9c1",
  "retry_allowed": true,
  "max_retries": 1
}
Enter fullscreen mode Exit fullscreen mode

The mobile app sends this challenge ID back with the Turnstile token:

{
  "challenge_id": "chal_8f72a9c1",
  "turnstile_token": "TOKEN_FROM_WEBVIEW",
  "original_request_id": "req_12345",
  "device_id": "hashed-device-id"
}
Enter fullscreen mode Exit fullscreen mode

Backend rules:

if challenge_id is already used: deny replay
if challenge_id is expired: deny challenge
if device or IP exceeded challenge limit: deny or cooldown
if Siteverify succeeds: mark challenge_id used and issue clearance
Enter fullscreen mode Exit fullscreen mode

This prevents attackers from repeatedly reusing the same application challenge.


Step 9: Decide where risk is calculated

The backend should calculate the final risk decision.

Cloudflare contributes edge signals and enforces first-layer controls. The backend decides whether the request should be allowed, challenged, rate-limited, denied, or cooled down.

Function Owner
Bot score, WAF signal, IP reputation Cloudflare
Edge rate limiting Cloudflare
User/device/account rate limiting Backend
Turnstile token generation Cloudflare
Turnstile token validation Backend via Siteverify
Final risk decision Backend
App clearance token issuance Backend
Business abuse detection Backend

A simple backend risk function is enough to start. It does not need to be machine learning.

export function calculateRisk(request, signals) {
  let risk = 0;

  if (signals.cloudflareBotScore !== undefined && signals.cloudflareBotScore < 30) {
    risk += 30;
  }

  if (signals.cloudflareWafAttackScore !== undefined && signals.cloudflareWafAttackScore < 40) {
    risk += 25;
  }

  if (signals.ipIsKnownBad) {
    risk += 25;
  }

  if (signals.asnIsHighAbuse) {
    risk += 15;
  }

  if (
    request.path === "/api/otp/request" ||
    request.path === "/api/auth/register" ||
    request.path.startsWith("/api/payment/")
  ) {
    risk += 30;
  }

  if (request.path === "/api/auth/login") {
    risk += 20;
  }

  if (signals.failedLoginCount15m > 5) {
    risk += 40;
  }

  if (signals.otpRequests10m > 2) {
    risk += 50;
  }

  if (signals.requestsByDevice5m > signals.deviceRequestThreshold) {
    risk += 30;
  }

  if (signals.manyUsernamesFromSameDevice15m) {
    risk += 50;
  }

  if (signals.clearanceFailures15m > 3) {
    risk += 50;
  }

  if (signals.hasValidAppClearance) {
    risk -= 40;
  }

  if (signals.hasValidAppAttestation) {
    risk -= 30;
  }

  if (signals.hasEstablishedNormalSession) {
    risk -= 20;
  }

  return Math.max(0, Math.min(100, risk));
}
Enter fullscreen mode Exit fullscreen mode

Decision model:

Risk score Action
0-29 Allow normally
30-49 Allow with rate limit or monitoring
50-79 Return TURNSTILE_REQUIRED
80-100 Deny, cooldown, or require stronger verification

Tune these thresholds with real traffic. Start conservative, monitor false positives, and adjust.


Step 10: Backend request flow

This is the core protected API logic:

export async function handleProtectedApi(request, context) {
  const signals = await context.signalService.collect(request);
  const risk = calculateRisk(request, signals);

  const requiresClearance = context.policy.requiresClearance({
    path: request.path,
    method: request.method,
    risk
  });

  if (!requiresClearance) {
    return context.api.process(request);
  }

  const clearance = await context.clearanceService.validate(
    request.headers["x-app-clearance"],
    request
  );

  if (clearance.valid && clearance.scope.includes(request.path)) {
    if (clearance.maxUsesExceeded) {
      return context.responses.forbidden({
        error: "CLEARANCE_EXPIRED"
      });
    }

    await context.clearanceService.incrementUse(clearance.id);
    return context.api.process(request);
  }

  const challenge = await context.challengeService.create({
    deviceId: request.deviceId,
    ip: request.clientIp,
    endpoint: request.path,
    originalRequestId: request.requestId,
    expiresInSeconds: 300,
    maxRetry: 1
  });

  return context.responses.forbidden({
    error: "TURNSTILE_REQUIRED",
    challenge_id: challenge.id,
    retry_allowed: true,
    max_retries: 1
  });
}
Enter fullscreen mode Exit fullscreen mode

The backend verification endpoint then validates the Turnstile token and issues clearance:

export async function handleTurnstileVerify(request, context) {
  const {
    challenge_id: challengeId,
    turnstile_token: turnstileToken,
    original_request_id: originalRequestId,
    device_id: deviceId
  } = request.body;

  if (await context.rateLimiter.tooManyTurnstileAttempts(deviceId, request.clientIp)) {
    return context.responses.tooManyRequests({
      error: "SECURITY_VERIFICATION_LIMITED",
      retry_after_seconds: 900
    });
  }

  const challenge = await context.challengeService.get(challengeId);

  if (!challenge || challenge.used || Date.now() > challenge.expiresAt) {
    return context.responses.forbidden({
      error: "SECURITY_VERIFICATION_FAILED"
    });
  }

  if (challenge.originalRequestId !== originalRequestId) {
    return context.responses.forbidden({
      error: "SECURITY_VERIFICATION_FAILED"
    });
  }

  const verification = await context.turnstileService.verify({
    challengeId,
    turnstileToken,
    clientIp: request.clientIp
  });

  if (!verification.allowed) {
    await context.rateLimiter.recordTurnstileFailure(deviceId, request.clientIp);

    return context.responses.forbidden({
      error: "SECURITY_VERIFICATION_FAILED"
    });
  }

  await context.challengeService.markUsed(challengeId);

  const clearance = await context.clearanceService.issue({
    deviceId,
    userId: request.user?.id || null,
    sessionId: request.sessionId || null,
    endpointScope: [challenge.endpoint],
    challengeId,
    ttlSeconds: context.policy.clearanceTtlSeconds(challenge.endpoint),
    maxUses: context.policy.clearanceMaxUses(challenge.endpoint)
  });

  return context.responses.ok({
    app_clearance_token: clearance.token,
    expires_in: clearance.expiresIn
  });
}
Enter fullscreen mode Exit fullscreen mode

These examples intentionally assume service abstractions for policy, rate limiting, challenge storage, and response handling. That keeps the security model clear and portable across frameworks.


Step 11: Protect the origin

Turnstile and WAF controls are not useful if attackers can bypass Cloudflare and call the origin directly.

Minimum origin protection:

API hostname is proxied through Cloudflare
origin only accepts traffic from Cloudflare or a private path
direct-to-origin traffic is blocked
backend trusts CF-* headers only from Cloudflare-sourced traffic
mTLS or Authenticated Origin Pulls is used where possible
Enter fullscreen mode Exit fullscreen mode

Cloudflare documents several origin protection options, including Cloudflare Tunnel, Authenticated Origin Pulls, and allowlisting Cloudflare IP addresses at the origin.

Common pattern: allow only Cloudflare IPs

If the origin must remain public behind a load balancer, restrict inbound access at the cloud firewall, security group, load balancer ACL, or Kubernetes ingress layer.

Example AWS pattern:

ALB or EC2 security group
  -> allow TCP 443 from Cloudflare IPv4 ranges
  -> allow TCP 443 from Cloudflare IPv6 ranges
  -> deny all other public inbound traffic
Enter fullscreen mode Exit fullscreen mode

Do not maintain those ranges manually. Cloudflare publishes the official IP ranges:

https://www.cloudflare.com/ips-v4
https://www.cloudflare.com/ips-v6
Enter fullscreen mode Exit fullscreen mode

Recommended automation:

scheduled job or CI pipeline
  -> fetch Cloudflare IPv4 and IPv6 ranges
  -> validate the fetched lists are not empty
  -> compare with current firewall or prefix list
  -> add new ranges first
  -> run health checks through Cloudflare
  -> remove stale ranges only after validation
  -> alert on failure
Enter fullscreen mode Exit fullscreen mode

This avoids outages caused by stale Cloudflare IP allowlists.

Stronger option: Authenticated Origin Pulls

Authenticated Origin Pulls adds mTLS between Cloudflare and the origin so the origin can verify that requests came through Cloudflare. Cloudflare notes that without this type of protection, someone who discovers the origin IP can send requests directly and bypass Cloudflare protections.

Authenticated Origin Pulls must be configured in both places:

Cloudflare dashboard
  -> SSL/TLS
  -> Origin Server
  -> Authenticated Origin Pulls

Origin server or ingress
  -> require Cloudflare client certificate
  -> reject requests without a valid client certificate
Enter fullscreen mode Exit fullscreen mode

Enabling it only in Cloudflare is not enough. The origin must enforce certificate validation.


Step 12: Add Cloudflare WAF and rate limiting

Turnstile should not be the only control. Add Cloudflare WAF and rate limiting around high-risk API paths.

Suggested starting controls:

Endpoint Starting control
/api/auth/login Rate limit by IP and account identifier where possible
/api/otp/request Strict rate limit
/api/auth/register Require clearance token
/api/graphql Block malformed or high-volume requests
/api/payment/* Require fresh clearance
/api/search Rate limit anonymous or high-volume use

Use block mode only for obvious abuse. For suspicious but uncertain traffic, prefer rate limiting, backend clearance requirements, or staged rollout.


Step 13: Logging and detection

Log these application events:

turnstile_challenge_created
turnstile_token_received
turnstile_siteverify_success
turnstile_siteverify_failed
turnstile_siteverify_timeout
app_clearance_issued
app_clearance_missing
app_clearance_expired
app_clearance_replay_detected
security_verification_limited
high_risk_api_blocked
Enter fullscreen mode Exit fullscreen mode

Send these sources to your SIEM or logging platform:

Cloudflare WAF logs
Cloudflare Turnstile analytics
API gateway logs
backend auth logs
backend rate-limit logs
mobile app version and device telemetry
Enter fullscreen mode Exit fullscreen mode

Useful alerts:

Detection Why it matters
High Siteverify failure rate from one IP/device Token replay, scripted abuse, or broken client
Many clearance requests from one device Bot loop or automation
Repeated expired or duplicate Turnstile tokens Replay or timing issue
High API volume after successful clearance Clearance token being abused
Login or OTP abuse by ASN/country/IP range Credential stuffing or SMS/email cost attack
Direct-to-origin attempts Cloudflare bypass attempt

Do not auto-block aggressively on the first signal. Use staged response: rate limit, cooldown, deny, then edge block after confidence increases.


Implementation checklist

Use this as the engineering rollout checklist.

1. Keep Turnstile widget mode set to Invisible.
2. Add the exact hostname used by the mobile WebView challenge page.
3. Copy the site key and secret key.
4. Store the secret key only in backend secret management.
5. Build the /mobile-turnstile page using the site key.
6. Make the mobile app open /mobile-turnstile in a WebView.
7. Pass the Turnstile token from WebView to the native app.
8. Create POST /api/security/turnstile/verify.
9. Validate Turnstile tokens server-side with Cloudflare Siteverify.
10. Use idempotency_key for safe Siteverify retries.
11. Issue short-lived, scoped app_clearance_token after successful verification.
12. Require X-App-Clearance only on selected high-risk APIs.
13. Limit automatic retry to one retry per original API request.
14. Add challenge_id replay protection.
15. Add per-device, per-user, per-IP, and per-endpoint rate limits.
16. Protect the origin from direct-to-origin bypass.
17. Add Cloudflare WAF and rate limits for high-risk paths.
18. Send Cloudflare and backend security logs to the SIEM.
19. Monitor false positives and tune thresholds before broad rollout.
Enter fullscreen mode Exit fullscreen mode

Final implementation position

The clean production pattern is:

Cloudflare Turnstile:
  invisible challenge execution and token generation

Backend:
  Siteverify validation
  risk decision
  challenge lifecycle
  app clearance token issuance
  API enforcement

Cloudflare WAF/rate limiting:
  edge filtering and volumetric protection

Origin controls:
  prevent Cloudflare bypass
Enter fullscreen mode Exit fullscreen mode

That design avoids three common mistakes:

sending Turnstile tokens on every API request
creating an infinite mobile verification loop
letting attackers bypass Cloudflare and hit the origin directly
Enter fullscreen mode Exit fullscreen mode

Invisible Turnstile is useful, but it becomes production-grade only when paired with backend Siteverify validation, scoped clearance tokens, bounded retries, API-specific enforcement, rate limits, logging, and origin protection.

Top comments (0)