Cap integration checklist

Use this page to verify the widget, backend token verification, proxy headers, geo checks, country allowlists, and filtering before you put Cap in front of a protected flow.

1. Add the widget

Load the widget script and point it at this Cap instance with your site key.

<script src="https://cap-monster.run/assets/widget.js" async defer></script>

<cap-widget
  data-cap-api-endpoint="https://cap-monster.run/YOUR_SITE_KEY/"
></cap-widget>

2. Verify on your server

Never trust the browser alone. Send the Cap token to your backend and verify it with your secret key.

const res = await fetch("https://cap-monster.run/siteverify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    secret: "YOUR_SECRET_KEY",
    response: capToken
  })
});

const result = await res.json();
if (!result.success) throw new Error("Captcha failed");

3. Forward real visitor headers

Cap needs the real client IP for rate limits, ASN detection, country checks, and block rules. Your reverse proxy should forward these headers.

RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"
RequestHeader set X-Forwarded-For expr=%{REMOTE_ADDR}
RequestHeader set X-Real-IP expr=%{REMOTE_ADDR}

In Cap settings, use the matching IP header, or leave it empty to use the default order: X-Forwarded-For, X-Real-IP, CF-Connecting-IP.

4. Enable geo and country protection

For country allowlists and country block rules, Cap needs one of these geo sources:

IP database mode, recommended for your current setup.
Proxy country header, for example CF-IPCountry behind Cloudflare.

Then configure your key under Configuration -> Security -> Request filtering -> Only allow selected countries.

5. Handling Blocks & Redirecting

If a visitor is blocked (e.g. by ASN, country allowlist, or invalid headers), you can automatically redirect them to another page. The easiest way is to add the data-cap-redirect-on-block attribute directly to the widget:

<cap-widget
  data-cap-api-endpoint="https://cap-monster.run/YOUR_SITE_KEY/"
  data-cap-redirect-on-block="https://google.com"
></cap-widget>

Alternatively, you can listen for the error event in JavaScript for custom logic:

document.querySelector("cap-widget").addEventListener("error", (e) => {
  if (e.detail?.message === "Blocked") {
    window.location.href = "https://google.com";
  }
});

6. What Cap checks

Proof of work Instrumentation Rate limits User-Agent filter Required browser headers Country allowlist IP/CIDR/ASN/country block rules CORS origins

7. Quick test

Open your protected page in a normal browser from an allowed country.
Network tab should show POST /YOUR_SITE_KEY/challenge with status 200.
Your backend should call /siteverify before allowing the protected action.
Requests from blocked countries, ASNs, missing headers, or non-browser clients should return 403.