CAPTCHA

Magic-code and password sign-in attract abuse. Bot networks spam send-code to every known email to phish, run credential-stuffing dictionaries against /password/login, or use up SMS quotas through /phone/send-code. Pylon’s built-in CAPTCHA gate protects those endpoints. Set one env var pair, and Pylon blocks unauthenticated bots before they reach the rate limiter. Three providers are built in:

hCaptcha — independent, privacy-focused, free up to ~1M/month
Cloudflare Turnstile — invisible challenge, free for any volume
Google reCAPTCHA — v2 + v3 token shapes

Gated endpoints

When PYLON_CAPTCHA_PROVIDER + PYLON_CAPTCHA_SECRET are both set, these endpoints require a captchaToken in the request body:

Endpoint	Method	Why gated
`/api/auth/magic/send`	POST	Bot can send-code-spam every email in a list to phish or harvest
`/api/auth/password/register`	POST	Trivial account creation → spam content / abuse fanout
`/api/auth/phone/send-code`	POST	Burns Twilio (or other SMS provider) quotas
`/api/auth/magic-link/send`	POST	Same as magic/send but for password-reset links

When the env vars are unset, Pylon skips the gate. Existing apps keep working unchanged.

Configuration

PYLON_CAPTCHA_PROVIDER=hcaptcha     # hcaptcha | turnstile | cloudflare | recaptcha | google
PYLON_CAPTCHA_SECRET=0xCAPTCHA_secret_from_provider_dashboard

Provider aliases:

turnstile and cloudflare both select Turnstile.
recaptcha and google both select reCAPTCHA.

The framework calls each provider’s siteverify endpoint with the supplied token and the request’s peer IP:

hCaptcha: https://api.hcaptcha.com/siteverify
Turnstile: https://challenges.cloudflare.com/turnstile/v0/siteverify
reCAPTCHA: https://www.google.com/recaptcha/api/siteverify

The client-side public site key lives in your frontend; the server-side secret lives in PYLON_CAPTCHA_SECRET. Get both from the provider’s dashboard.

Client integration

<!-- hCaptcha example -->
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>

<form id="signup">
  <input type="email" name="email" />
  <div class="h-captcha" data-sitekey="<your hCaptcha site key>"></div>
  <button>Send code</button>
</form>

<script>
  document.getElementById("signup").addEventListener("submit", async (e) => {
    e.preventDefault();
    const email = e.target.email.value;
    const captchaToken = e.target.querySelector("[name='h-captcha-response']").value;

    await fetch("/api/auth/magic/send", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email, captchaToken }),
    });
  });
</script>

For Turnstile, the form input is cf-turnstile-response; for reCAPTCHA it’s g-recaptcha-response. All three map to a single captchaToken field in the request to Pylon.

Verify behavior

Missing or invalid token returns 400 CAPTCHA_FAILED:

{
  "error": {
    "code": "CAPTCHA_FAILED",
    "message": "CAPTCHA verification failed"
  }
}

Pylon logs the provider response (error codes like missing-input-response, invalid-input-response) server-side with tracing::warn!. Operators can debug from logs. The client does not learn which check failed. The gate runs before the rate limiter and before any DB or email work. Bots that fail the challenge do not consume rate-limit budget or trigger later actions.

Where to go next

Magic codes — primary gated endpoint
Password — register flow uses the same gate
Phone / SMS — /phone/send-code is gated identically

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Migrate

Gated endpoints

Configuration

Client integration

Verify behavior

Where to go next

​Gated endpoints

​Configuration

​Client integration

​Verify behavior

​Where to go next

Gated endpoints

Configuration

Client integration

Verify behavior

Where to go next