PyTurnstile

A Python library for validating Cloudflare Turnstile tokens with both async and sync support.

Features

• 🔄 Async & Sync Support
• 🚀 Simple & Intuitive API
• ✅ Type-safe response handling
• 🛡️ Enhanced security validation

What is PyTurnstile?

PyTurnstile simplifies Cloudflare Turnstile token validation. It handles all communication with Cloudflare's API.

sequenceDiagram
    participant Frontend as 🖥️ Frontend
    participant Backend as 🐍 Your Backend
    participant Cloudflare as ☁️ Cloudflare

    Frontend->>Cloudflare: 1. Complete challenge
    Cloudflare-->>Frontend: 2. Return token
    Frontend->>Backend: 3. Submit form + token

    rect rgb(50, 179, 238)
        Note over Backend,Cloudflare: 🔍 PyTurnstile handles this
        Backend->>Cloudflare: 4. Verify token
        Cloudflare-->>Backend: 5. Valid ✅ / Invalid ❌
    end

    Backend->>Frontend: 6. Allow / Deny request

Loading

If the diagram above doesn't load, click here

Learn more at: https://developers.cloudflare.com/turnstile/

Installation

Install the package using your preferred dependency manager.

uv

uv add pyturnstile

pip

pip install pyturnstile

Usage

Tip

You can follow this documentation and create your own Turnstile secret key at the Cloudflare Turnstile dashboard.

Quick Start

PyTurnstile provides two ways to validate tokens:

1. Using the Turnstile class (Recommended)

from pyturnstile import Turnstile

turnstile = Turnstile(secret="your-secret-key")

response = turnstile.validate(token="user-token-from-frontend")

# or validate asynchronously
# response = await turnstile.async_validate(token="user-token-from-frontend")

if response.success:
    print("✅ Token is valid!")

2. Using functions directly

from pyturnstile import validate, async_validate

response = validate(
    token="user-token-from-frontend",
    secret="your-secret-key"
)

# or validate asynchronously
# response = await async_validate(
#     token="user-token-from-frontend",
#     secret="your-secret-key"
# )

if response.success:
    print("✅ Token is valid!")

Optional Parameters

Note

For more details on all available parameters, see the Cloudflare documentation

response = turnstile.validate(
    token="user-token",               # The token from the client-side widget
    idempotency_key="unique-uuid",    # Optional: UUID for retry protection
    expected_remoteip="203.0.113.1",  # Optional: The visitor's IP address that the challenge response must match
    expected_hostname="example.com",  # Optional: The hostname that the challenge response must match
    expected_action="submit_form",    # Optional: The action identifier that the challenge must match
    timeout=10                        # Optional: request timeout in seconds
)

Response Object

Note

For more details on all response fields, see the Cloudflare documentation

The TurnstileResponse object contains:

response.success                   # bool: Whether validation succeeded
response.error_codes               # list[TurnstileErrorCodes]: Error codes (if any)
response.challenge_ts              # str: ISO timestamp of challenge completion
response.hostname                  # str: Hostname where challenge was served
response.action                    # str: Custom action identifier
response.cdata                     # str: Custom data payload from client-side
response.metadata["ephemeral_id"]  # Device fingerprint ID (Enterprise only)

Contributing

Any contributions are greatly appreciated. If you have a suggestion that would make this project better, please fork the repo and create a Pull Request. You can also open an issue.

License

Published under the MIT License.