Clearance Enforcement

What it is

Most bot defenses enforce on IP or fingerprint — both of which rotate. Clearance enforcement flips the model: real browsers earn a signed wd_clearance token, and enforcement checks one thing per request — does this request carry a valid token? A bot on 10,000 IPs still needs a valid token on each request and can’t mint one. A real human on any IP passes silently.

The rotation-proof part is the loop with your deception surfaces: if a session that holds a token trips one of your decoys — or an SDK tripwire planted in your own pages — WebDecoy denies that browser’s fingerprint — its token is revoked within about a minute and it can never mint another, on any IP.

Note

Clearance enforcement requires deploying a lightweight edge validator (a Cloudflare Worker or an AWS Lambda@Edge function). Detection, analytics, and the fingerprint-rule layer work without it.

How a request is decided

At the edge, each request passes if any of these hold, checked in order:

1. Machine service token — a credential you issued for a partner, monitor, or job (see Response Actions).
2. Verified bot — Googlebot, Bingbot, AI crawlers, and monitoring services you’ve allowed (verified by the platform / reverse-DNS, never by User-Agent).
3. Unscoped route — the path isn’t in your token-enforced route list, so no token is required.
4. Valid wd_clearance cookie — a real browser that already passed the client check, and whose fingerprint hasn’t been denied by tripping a decoy.

If none hold:

• Monitor mode — the request passes anyway, tagged with an x-wd-clearance header so you can see what enforce mode would do.
• Enforce mode — the browser gets a one-time invisible check that mints a token and reloads; non-browser clients get a 403.

Configure everything on the Enforcement page (sidebar → Enforcement): the token-enforced routes in step 2 (Set up the clearance token), the crawler allowlist and machine credentials in step 4 (Allow tokenless clients), and the Monitor/Enforce mode in step 5 (Go live).

Setup

1. Add the client script

The @webdecoy/client script mints the wd_clearance cookie for real browsers during normal browsing. Add it to your site with your site key (shown on the Enforcement page, step 2 — Set up the clearance token):

<script src="https://cdn.webdecoy.com/client/webdecoy.global.js"
        data-site-key="YOUR_SITE_KEY"
        async></script>

Attribute	Required	Description
data-site-key	yes	Your publishable site key (the organization ID).
data-ingest	no	WebDecoy ingest origin. Defaults to https://ingest.webdecoy.com.
data-scope	no	Route-group scope for the token. Defaults to tenant-wide.

Minting is deferred to browser idle time, runs at most once per session, and skips entirely when a fresh cookie already exists — it adds no page-load cost and never blocks paint or interaction.

2. Deploy the edge validator

The validator runs at your CDN edge and fails open on any error — if it can’t reach WebDecoy or can’t verify a token, it forwards the request untouched, so it can never take your site down. Pick the one matching your CDN:

Both validators live in the public WebDecoy/clearance-validators repo, and the Enforcement page (step 3) pre-fills the config for your organization:

• Cloudflare — one-click Deploy to Cloudflare installs the Worker into your account; then add a route for your domain using the pre-filled wrangler.toml variables shown in the dashboard.
• AWS / CloudFront — a Lambda@Edge function on your distribution’s viewer-request behavior: set your keys in src/config.ts, build and zip, upload to S3 in us-east-1, then launch the provided CloudFormation template and attach the published function version to your distribution. Because AWS has no platform-verified-bot signal, this validator verifies crawlers itself via forward-confirmed reverse DNS.

3. Verify the deployment

On the Enforcement page, step 3 (Deploy the edge validator), enter your site domain and click Verify deployment. The dashboard checks — from your own browser — that the validator is answering on your zone, and reports its current mode. Since the validator fails open, this check is how you confirm it’s actually live before you rely on it. That panel also gives you the pre-filled config (your site key and route already filled in) for both Cloudflare and AWS.

4. Roll out in monitor mode first

Leave enforcement in monitor mode, watch the x-wd-clearance header in your logs to see the pass/challenge split, then flip to enforce once it looks right.

Privacy and stability notes

• The wd_clearance cookie is a first-party cookie on your domain. The decoy → deny loop fires when a decoy shares an origin with your pages (decoy links/endpoints on your own site). Off-domain decoys don’t carry the cookie.
• The device fingerprint uses stable browser characteristics (canvas, WebGL, screen, timezone, platform, language). Privacy browsers that randomize canvas will simply re-mint each visit — enforcement still holds within a session.
• No User-Agent is used in the fingerprint, so a browser update doesn’t churn a user’s identity.