Django CAPTCHA integration

The official Django SDK.

The TrustedCaptcha Django SDK is open-source (MIT) and developed in the open at github.com/trustedcaptcha. It wraps the /api/v1/siteverify endpoint, handles secret lookup from environment, exposes a typed verification result, and provides the framework's idiomatic integration points (validation rule / form field / middleware as appropriate).

Install.

pip install trustedcaptcha-django

Sample integration.

# settings.py
INSTALLED_APPS += ["trustedcaptcha"]
TRUSTEDCAPTCHA_SITEKEY = "0x..."
TRUSTEDCAPTCHA_SECRET  = os.environ["TC_SECRET"]

# forms.py
from trustedcaptcha.fields import TrustedCaptchaField

class ContactForm(forms.Form):
    email = forms.EmailField()
    captcha = TrustedCaptchaField()

Why the SDK rather than rolling your own.

It's small enough you absolutely could roll your own — the verify call is one HTTP POST. The SDK exists because there are a handful of details worth getting right that aren't obvious from the API docs alone:

• Token validation — making sure the token shape matches before sending it (avoids burning rate-limit budget on malformed input).
• Timeout handling — what happens when the verify call times out. The SDK fails closed by default but exposes a "fail open" mode for non-critical surfaces where availability matters more than perfect bot blocking.
• Score thresholds — the SDK exposes the score as a typed result; your form-handler decides what to do with it. Default threshold is 0.50 to match the dashboard's default.
• IP forwarding — picking the right header (X-Forwarded-For vs X-Real-IP vs the platform's idiom). The SDK uses your framework's standard helper.
• Localization — passing the user's locale through to the verify call so error messages come back in the right language.

Test mode.

The SDK includes a test mode: when TC_SITEKEY is the documented test value (0x10000000000000000000000000000000ee), all verifications succeed locally without an HTTP call to our service. Useful for unit and integration tests without burning real verification budget.

Type safety.

The Django SDK includes typed return values for the verification result (success, score, mode, hostname, action, error_codes). You get autocomplete on the result fields rather than indexing into a generic associative array.

Rate limiting.

If your application can be DoS'd by sending many invalid tokens to verify, the SDK includes optional rate-limit guards keyed by IP. Default is off; enable with one configuration flag.

Help.

SDK issues on GitHub. Account/billing/integration help: support@trustedcaptcha.com.

Start free →   SDK on GitHub →