Session Clearance

Session clearance is WebDecoy’s enforcement gate for browser traffic. Instead of blocklisting fingerprints and IP addresses — which either miss rotating bots or catch innocent users — protected routes require a signed clearance token, carried in the wd_clearance cookie. Real browsers earn one automatically. A client that trips a decoy or SDK tripwire is denied clearance on every IP it rotates to, and its current token is revoked within about a minute.

Requirements

• Your site proxied through Cloudflare — the clearance gate runs as a Cloudflare Worker at your edge
• The SDK script tag installed with your site key, so real browsers earn tokens in the background as they browse
• Enforcement mode set to Enforce (Monitor is the default)
• At least one token-enforced route scoped — with no routes scoped, the gate stays off even in Enforce mode

How the loop works

1. Mint in the background — the SDK script tag silently mints the wd_clearance cookie while a visitor browses their first pages; no interstitial, nothing to click. A visitor who deep-links straight to an enforced route before the cookie exists gets a one-time invisible check that mints it and reloads.
2. Verify at the edge — subsequent requests carry the cookie, and the edge validates it with no round-trip to your origin.
3. Deception revokes — a decoy or SDK tripwire hit that carries the cookie automatically puts that client’s token fingerprint on the deny-list: it cannot mint a new token from any IP, and its live token stops validating within about a minute. Denials last 30 days by default and can be revoked manually at any time. By design, only deception signals feed the deny-list — heuristic rules like rate limits and filters never do.

Client	What happens on an enforced route
Real browser	Passes the check once, carries clearance, never sees it again
Verified crawler (e.g. Googlebot)	Passes via the verified-crawler allowlist — never challenged
Your own machine clients	Pass via a machine service token
Bot that trips a decoy or tripwire	Deny-listed: current token revoked, re-minting refused, on every IP

Setup

Everything lives on the Enforcement page (sidebar → Enforcement), organized as a five-step pipeline: Connect your WAF → Set up the clearance token → Deploy the edge validator → Allow tokenless clients → Go live.

Enforcement mode

Mode	Behavior
Monitor (default)	WebDecoy generates would-enforce signals but pushes and blocks nothing. Review here first.
Enforce	Live enforcement — the clearance gate is active on scoped routes, and confirmed detections push to your connected WAF.

Clearance token setup

• Site key — your organization ID; publishable, used by the client to mint tokens.
• Token-enforced routes — path patterns (e.g. /checkout/*) where the gate applies. Scope it to what your protection covers: login, checkout, the endpoints being scraped. Everything else is untouched, so normal browsing carries zero friction.
• Cloudflare zone check — a preflight that round-trips a harmless canary rule to verify the connection. It changes no live traffic.

Tokenless clients

Legitimate clients that never run a browser pass the gate through two allowlist paths, both checked before the token requirement:

• Verified crawlers — category toggles for search engines and other known crawlers, verified against operator-published ranges and forward-confirmed reverse DNS. A cloud VM claiming to be Googlebot fails both checks.
• Machine service tokens — per-client credentials for your partners, monitors, and jobs, sent in a request header. Each token is shown once at creation; revoking one cuts off that client immediately with no shared blast radius.

There is deliberately no IP-range allowlist: proof, not provenance.

Denying and un-denying actors

• Automatic — a decoy hit carrying a clearance cookie denies the actor. This is the closed loop: deterministic honeypot evidence, not a behavioral guess.
• Manual — every actor detail page has Deny actor / Remove deny controls.
• API —

GET/PUT  /api/organizations/{organization_id}/enforcement/mode
GET/POST /api/organizations/{organization_id}/enforcement/denylist
DELETE   /api/organizations/{organization_id}/enforcement/denylist/{device_fp}
GET/POST /api/organizations/{organization_id}/enforcement/routes
DELETE   /api/organizations/{organization_id}/enforcement/routes/{route_id}

Boundaries worth knowing

Embed decoys on your protected origin

The automatic decoy-to-deny binding fires when the decoy shares an origin with the pages that set the clearance cookie — that is, decoy links and endpoint decoys embedded in your own pages. Decoys hosted off-domain (the shared *.d.webdecoy.com domain or a separate custom decoy domain) don’t receive the first-party cookie, so those hits still detect, score, and correlate to the actor as always — but they can’t auto-deny its token. To arm the binding, embed at least some decoys on the origin you’re protecting.

Monitor-mode coverage

The SDK script tag mints clearance cookies in the background in both modes, so monitor mode produces a realistic pass/challenge picture before you ever enforce: the edge tags every request with an x-wd-clearance header showing what enforce mode would have done. Sessions without the script installed — or visitors who deep-link before the background mint completes — show as tokenless in that tag.

For the full per-request decision order and edge validator deployment, see Clearance Enforcement.

How this relates to WAF rules

Fingerprint and IP rules pushed by Response Actions remain the right tool for datacenter and scripted bots, whose TLS stacks stand out and where a fingerprint block is safe. Session clearance is the gate for browser-shaped traffic — the residential rotators that no fingerprint or IP rule can block without collateral. The two layers run together.

---

Next Steps

• Response Actions — WAF-rule automation for the datacenter layer
• Actors — the identity model, and where deny controls live
• Decoy Links — the ground truth that drives revocation