1# Cloudflare Turnstile Implementation Skill Reference
2 
3Expert guidance for implementing Cloudflare Turnstile - a smart CAPTCHA alternative that protects websites from bots without showing traditional CAPTCHA puzzles.
4 
5## Overview
6 
7Turnstile is a user-friendly CAPTCHA alternative that runs challenges in the background without user interaction. It validates visitors automatically using signals like browser behavior, device fingerprinting, and machine learning.
8 
9## Widget Types
10 
11| Type | Interaction | Use Case |
12|------|-------------|----------|
13| **Managed** (default) | Shows checkbox when needed | Forms, logins - balance UX and security |
14| **Non-Interactive** | Invisible, runs automatically | Frictionless UX, low-risk actions |
15| **Invisible** | Hidden, triggered programmatically | Pre-clearance, API calls, headless |
16 
17## Quick Start
18 
19### Implicit Rendering (HTML-based)
20```html
21<!-- 1. Add script -->
22<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
23 
24<!-- 2. Add widget to form -->
25<form action="/submit" method="POST">
26  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
27  <button type="submit">Submit</button>
28</form>
29```
30 
31### Explicit Rendering (JavaScript-based)
32```html
33<div id="turnstile-container"></div>
34<script src="https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"></script>
35<script>
36window.turnstile.render('#turnstile-container', {
37  sitekey: 'YOUR_SITE_KEY',
38  callback: (token) => console.log('Token:', token)
39});
40</script>
41```
42 
43### Server Validation (Required)
44```javascript
45// Cloudflare Workers
46export default {
47  async fetch(request) {
48    const formData = await request.formData();
49    const token = formData.get('cf-turnstile-response');
50    
51    const result = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
52      method: 'POST',
53      headers: { 'Content-Type': 'application/json' },
54      body: JSON.stringify({
55        secret: env.TURNSTILE_SECRET,
56        response: token,
57        remoteip: request.headers.get('CF-Connecting-IP')
58      })
59    });
60    
61    const validation = await result.json();
62    if (!validation.success) {
63      return new Response('Invalid CAPTCHA', { status: 400 });
64    }
65    // Process form...
66  }
67}
68```
69 
70## Testing Keys
71 
72**Critical for development/testing:**
73 
74| Type | Key | Behavior |
75|------|-----|----------|
76| **Site Key (Always Passes)** | `1x00000000000000000000AA` | Widget succeeds, token validates |
77| **Site Key (Always Blocks)** | `2x00000000000000000000AB` | Widget fails visibly |
78| **Site Key (Force Challenge)** | `3x00000000000000000000FF` | Always shows interactive challenge |
79| **Secret Key (Testing)** | `1x0000000000000000000000000000000AA` | Validates test tokens |
80 
81**Note:** Test keys work on `localhost` and any domain. Do NOT use in production.
82 
83## Key Constraints
84 
85- **Token expiry:** 5 minutes after generation
86- **Single-use:** Each token can only be validated once
87- **Server validation required:** Client-side checks are insufficient
88 
89## Reading Order
90 
911. **[configuration.md](configuration.md)** - Setup, widget options, script loading
922. **[api.md](api.md)** - JavaScript API, siteverify endpoints, TypeScript types
933. **[patterns.md](patterns.md)** - Form integration, framework examples, validation patterns
944. **[gotchas.md](gotchas.md)** - Common errors, debugging, limitations
95 
96## See Also
97 
98- [Cloudflare Turnstile Docs](https://developers.cloudflare.com/turnstile/)
99- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
100