Gate a whole site at your reverse proxy

The normal way to use Caputchin is to embed the widget on a page and verify the token from your backend. That needs a place to put the widget and a backend to check the token. The Proxy page-gate needs neither. It puts a full-page verification in front of a whole site or route at your reverse proxy: a visitor solves one game, earns a short-lived pass, and roams the site until the pass expires. The protected app is never touched.

Because nothing is added to the app itself, this is the way to protect hosts you cannot embed a script into, a compiled single-page login portal, an appliance, or an internal tool that sits behind an auth proxy.

Who it is for

Reach for the gate when the inline widget does not fit:

• The app has no place for the widget. A sealed login portal (like Authelia), a vendor appliance, or any UI you cannot edit.
• You want to gate a whole surface, not one form. "Prove you are human before you reach this site" rather than a check on a single submit.
• You have no backend to verify a token. The proxy does the enforcing; there is no /siteverify call to write.

For a normal page or form you control, embed the widget instead, it is lighter and does not redirect the visitor. If you have a form but no backend, hosted verification is the better fit.

How it works

One solve buys many requests. The visitor plays the game once; after that a first-party cookie clears their requests until it expires.

The proxy makes a small authorizer call to Caputchin on every request. When the request carries no valid pass, Caputchin answers 401 and the proxy redirects the visitor to the hosted challenge. When the pass is present and valid, Caputchin answers 204 and the proxy passes the request through to your app.

The clearance cookie

The pass lives in a first-party cookie named cpt_gate, set on your own domain by a small callback you host. It is a signed, short-lived token, not tied to a device, so its safety comes entirely from the cookie attributes (HttpOnly, Secure, SameSite=Lax) and a short TTL you choose. Because it sets a cookie on your visitors, disclose it in your cookie policy. The set-up guide walks through the callback and the required attributes.

What is intentionally left out

• No self-hosted gate. Caputchin hosts the challenge and verifies the pass; you do not run a verifier. Your proxy only forwards a cookie and follows redirects.
• A per-request check, not local token validation. The proxy asks Caputchin on each request. The fail mode you pick (open or closed) decides what happens if Caputchin is briefly unreachable.
• Per-site-key, cookie-scoped clearance. A pass clears one origin, not a whole account or several domains, because it is an ordinary first-party cookie.
• Not a session or a login. The gate proves a human reached the site; your app still handles authentication and its own rate limits. The two stack.

See also

• Set up the Proxy page-gate — enable it and wire your proxy end to end.
• Reverse-proxy recipes — nginx, Traefik, Caddy, and the Authelia worked example.
• Proxy page-gate statistics — read the passthrough-to-challenge ratio.
• Hosted verification — the no-backend option when you do have a form to point at us.