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), which is a set of routed sub-pages rather than one long scroll:

Tab	What you do there
Overview (/enforcement)	switch between Monitor and Enforce, read the readiness checks, and see what the loop did
Policy (/enforcement/policy)	scope token-enforced routes, set each route’s minimum trust grade, and allow tokenless clients
Actions (/enforcement/actions)	Response Actions
Setup (/enforcement/setup)	the one-time wiring, in three steps: connect your WAF, set up the clearance token, deploy the edge validator
History (/enforcement/history)	the audit log, and the way back to an earlier configuration

The split matters for finding things: the wiring you touch once is on Setup, the controls that decide what is protected are on Policy, and the switch that makes any of it live is on Overview. A half-configured organization is told so on Overview, with a link into Setup, so an unfinished install is visible from the page you land on.

Getting here is also a step on the onboarding checklist, immediately after seeing your first detection, since the question of what should happen to that traffic only exists once you have caught some. The step completes on evidence that you engaged with the decision, not on flipping to Enforce, so nothing pushes you into blocking traffic before your preconditions pass.

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

On Setup, in the clearance token step:

• Site key: your organization ID; publishable, used by the client to mint tokens.
• Cloudflare zone check: a preflight that round-trips a harmless canary rule to verify the connection. It changes no live traffic.
• Turnstile attestation: optional, and the only way a session can reach the highest trust grade. See Device Attestation.

On Policy:

• 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.
• Minimum trust per route: how much positive human evidence a token must carry on that path, covered next.

Requiring a trust grade

A valid token is the floor, not the ceiling. Every route carries a minimum grade, set from the selector on its row, and each grade states what it asks of a real visitor:

Minimum	What a visitor has to present
Any valid token (default)	nothing extra. Every real browser passes without noticing, and clients that cannot run JavaScript are still refused, which is what scoping the route already does.
Human-likely	one positive human signal: a browser-integrity check, interaction cadence, or browser-like TLS. Most real visitors qualify silently.
Attested human	a passed Turnstile or Apple Private Access Token challenge. Anyone who has not already passed one is challenged before they get in.

Three properties are worth knowing before you raise a bar:

• No minimum accepts any valid token, including ones minted before grades existed, so routes you scoped earlier are unaffected until you set a grade on them.
• Evidence only ever raises a grade. Passing a challenge can lift a visitor; nothing they do afterwards lowers what they already earned.
• A bot-like threat score caps the grade. Attested human needs a threat score of 40 or below and human-likely 60 or below, so a client that looks automated cannot buy its way onto a graded route by passing a challenge.

Attested human with no attester configured refuses everyone

That grade is reachable only through Turnstile or an Apple Private Access Token, and Private Access Tokens are not yet available. Without a working Turnstile secret, no visitor can earn it, so requiring it turns the route into a closed door. The route row says so where the selector is, rather than letting a dropdown close a path silently. Configure attestation first, or stay at human-likely.

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
PATCH     /api/organizations/{organization_id}/enforcement/routes/{route_id}
DELETE    /api/organizations/{organization_id}/enforcement/routes/{route_id}

PATCH on a route is how a minimum trust grade is changed. It is a distinct endpoint on purpose: re-posting an existing pattern with a new grade returns the stored row untouched, so the bar would appear to move while nothing was written.

A detection flyout can deny the adversary it is describing, without a detour through the actor page first.

When a deny is not offered, the reason is stated rather than the control quietly disappearing. Either the actor has never been seen carrying a wd_clearance token, so there is no clearance identity to lock out, or its fingerprint is shared by unrelated clients and a deny would lock out whoever else arrives under it.

Putting a configuration back

History holds an append-only record of every enforcement change: mode flips, route scope, trust grades, allowlist toggles, credentials, and automatic decoy denies. It can be filtered by kind of change and narrowed to the last 24 hours, 7 days, or 30 days, and it distinguishes “nothing has ever happened” from “nothing matches this filter”.

Rows whose change left a saved configuration offer Restore this configuration, which puts the earlier policy back. Two boundaries are deliberate:

• It restores policy only: mode, scoped routes with their trust grades, and the crawler allowlist. Signing keys, machine credentials and the deny-list are excluded, because bringing those back would reverse a security decision rather than a configuration one. An undo that un-revokes a credential or un-denies an actor is worse than no undo.
• Restoring is itself undoable. The current configuration is captured before the restore is applied.

The restore is not one transaction, so if it fails partway the error names how far it got, and the page shows that rather than a generic failure that would misrepresent a partial apply as a clean one.

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.

Where the clearance identity comes from

wd_clearance is first-party to your domain, so the only sensor positioned to read it is the one running at your own edge. The browser tag posts to WebDecoy cross-origin and never sends the cookie, and a decoy served from a WebDecoy domain sees a cookie for the wrong site or none at all. The edge sensor now forwards the identity claim from the visitor’s cookie, which is what gives deny-at-mint a target to bind to. Without an edge sensor deployed, expect actors to show no clearance identity and deny-at-mint to have nothing to act on.

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