Clearance

A clearance is one signed record of a probe, or of a probe and the ceremony that followed it. It is a JWT signed with Ed25519 under a key pair that belongs to your site. Your server or edge verifies it with the site’s public key from GET /v1/clearance/keys; Heretic is never in the request path. Heretic signs what it measured, including a contradicted verdict, and never withholds or reads back the token. A probe-only token is typically about 1.1 KB; a ceremony adds its device record. Each measurement session opened counts as a probe, and each ceremony minted counts as a challenge against your plan. Reading a clearance cookie does not start another measurement.

Hosted page

Redirect an uncleared request to the hosted page. It runs the probe, escalates per the site’s clearance settings, and returns to your URL with heretic_clearance=<jwt> appended to the query.

https://heretic.tech/clearance?sitekey=hrtc_live_…&return=https://shop.example/account

return must be https://, or loopback http://, on the site’s registered domain. Any other value is refused on the page and never redirected. Start with the complete Cloudflare Worker gate in examples/cloudflare-worker/. Its README and configuration template cover installation on an existing website. The download also includes Node, Python and PHP verifiers for an application gate.

Create a site and verify its domain in the dashboard.
Set the hosted page’s lifetime and escalation settings on that site’s panel.
Configure the gate with the site’s public key and protected routes, then choose your admission rule.
Deploy the gate at your edge or in your application. Heretic hosts the verification page; your gate handles redirects and cookies.

The example binds the return to a random browser state, verifies the signed record, applies its admission rule, and sets an HttpOnly, Secure, host-only cookie. It strips the token from the URL before serving content. A rejected result receives 403. A key-service failure receives 503. Requests with bodies receive 403 until clearance is established, so a redirect never discards or replays a form submission. Protect every intended route, including API and export URLs. Keep public exceptions explicit. Restrict direct origin access so visitors cannot bypass your gate. Exclude callback tokens from access logs and analytics. For managed background preparation, reuse and action-time challenges, use the application SDK. The widget interface below remains available for custom integrations.

Background

Load guard.js with data-clearance="true". The embed starts the probe automatically; it may display a ceremony according to your escalation settings. Then data-clearance-callback receives the JWT. Post it to your own endpoint, which verifies it and sets the cookie for the next request.

<script src="https://heretic.tech/guard.js" async defer></script>

<div class="heretic-guard"
     data-sitekey="hrtc_live_0123456789abcdef01234567"
     data-clearance="true"
     data-clearance-callback="onClearance"></div>

<p id="clearance-status" role="status"></p>
<script>
  async function onClearance(jwt) {
    const status = document.getElementById('clearance-status');
    try {
      const reply = await fetch('/__heretic/clearance', {
        method: 'POST', body: jwt, credentials: 'same-origin',
        headers: { 'Content-Type': 'text/plain' },
      });
      if (reply.status !== 204) throw new Error('clearance refused');
      status.textContent = 'Verification accepted.';
      // Enable the protected action or continue to its URL here.
    } catch {
      status.textContent = 'Verification was not accepted.';
    }
  }
</script>

heretic.getClearance(id) reads the JWT of a widget rendered with the script API.

Guarded action

For a fresh single-use check, a form keeps the five-minute proof and siteverify. To reuse clearance, verify its cookie and apply your rule in the form handler instead. Clearance JWTs are not accepted by siteverify. Keep authentication, CSRF checks and action deduplication in your application. Configure the widget on the challenge widget page.

What the token contains

Header: alg is EdDSA, typ is JWT, and kid is site_<id>/<version>.

{
  "iss": "https://heretic.tech",
  "aud": "shop.example",
  "sub": "0123456789abcdef0123456789abcdef",
  "jti": "<32 hex, random>",
  "iat": 1757300000,
  "exp": 1757386400,
  "heretic": {
    "v": 1,
    "site_id": "site_…",
    "site_key": "hrtc_live_…",
    "verdict": "uncontradicted",
    "concealed": false,
    "challenged": false,
    "outcome": null,
    "probe": {
      "request_id": "0123456789abcdef0123456789abcdef",
      "measured_at": 1757299990000,
      "client_ip": "203.0.113.7",
      "network": { "asn": 133481, "country": "TH", "class": "access" },
      "identity": { "version": 3, "instance": "<64 hex>", "machine": "<64 hex>" }
    },
    "challenge": null
  }
}

Field	Meaning
`iss`	Always `https://heretic.tech`.
`aud`	The site’s registered domain. A gate on `www.` or a subdomain compares against the registered domain.
`sub`	The probe `request_id`, or the challenge id when no probe was read.
`jti`	Random, 32 hex.
`iat`, `exp`	Seconds. `iat` is fixed at the probe opening or ceremony completion; `exp` adds the site’s TTL. Re-exchanging a result does not renew its age. Your gate may require a shorter age from `iat`.
`heretic.v`	`1`.
`heretic.site_id`, `heretic.site_key`	The site the token was issued for.
`heretic.verdict`	`uncontradicted`, `contradicted`, or `refused`. `refused` with `probe: null` when the widget could not read the probe.
`heretic.concealed`	`true` when the original probe reported concealment or no original probe facts are available. A passed ceremony does not replace the original probe’s concealment flag.
`heretic.challenged`, `heretic.outcome`	`true` and `passed`, `contradicted`, or `not_completed` when a ceremony ran. Otherwise `false` and `null`.
`heretic.probe.request_id`	Keys `GET /v1/verdict`.
`heretic.probe.measured_at`	Milliseconds.
`heretic.probe.client_ip`, `heretic.probe.network`	The measured address, and its `asn`, `country`, and `class`.
`heretic.probe.identity`	`version`, `instance`, and `machine`. Each hash is 64 hex or `null`.
`heretic.challenge`	The ceremony when one ran. Otherwise `null`.

When a ceremony ran:

"challenge": {
  "id": "chg_…",
  "completed_at": 1757300100000,
  "device": {
    "request_id": "<32 hex>",
    "client_ip": "198.51.100.9",
    "network": { "asn": 5617, "country": "PL", "class": "access" },
    "identity": { "version": 3, "scope": "challenge-tenant-v1", "instance": "<64 hex>", "machine": "<64 hex>" }
  }
}

device is the device the ceremony cleared: the desktop in a QR hand-off, otherwise the phone. Its identity hashes are in the challenge scope. Compare them only with other ceremony devices, never with probe.identity.

Your rule

Verify the signature, iss, aud, iat, exp and site key, then apply your own rule. This example accepts an uncontradicted probe without concealment, or a passed ceremony, and requires the live request to come from the measured address and network. It is this site’s rule, not a Heretic threshold.

function allowed(payload, request) {
  const { verdict, concealed, challenged, outcome, probe, challenge } = payload.heretic;
  if (challenged ? outcome !== 'passed' : verdict !== 'uncontradicted' || concealed) return false;
  const device = challenged ? challenge?.device : probe;
  const ip = request.headers.get('cf-connecting-ip');
  return !!ip && !!device?.client_ip && device.client_ip === ip
    && Number.isInteger(device.network?.asn) && device.network.asn === request.cf?.asn;
}

Facts

The hosted page is the only placement that gates the first request. It adds a wait of a few seconds for each fresh probe; a ceremony takes longer. The page is distributed globally, and measurements currently run against the Warsaw sensor. A client that does not run the collector is never cleared. That includes search crawlers. What happens to an uncleared request is your rule. Findings and concealment indicators are not in the token. The visitor can read the token. Read them with your secret key at GET /v1/verdict/{request_id}.

Dashboard settings

On the site’s panel in the dashboard:

Setting	Meaning
TTL	Token lifetime. Default 86,400 s. 300 s to 30 days.
Escalation	Which probe results run a ceremony on the hosted page. `contradicted` (default, challenges contradicted and refused), `refused` (challenges only refused), `always`, `never`, as for `data-escalate`.
Challenge concealed	Also runs a ceremony when the probe reports concealment indicators. Default off.
Rotate signing key	Issues a new key version. See rotation.

Verifiers

The server examples include node/clearance.mjs, python/clearance.py, php/Clearance.php, and a Cloudflare Worker gate at examples/cloudflare-worker/clearance-gate.js.

Get started

Application integration

Collector

Challenge widget

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Clearance

Hosted page

Background

Guarded action

What the token contains

Your rule

Facts

Dashboard settings

Verifiers

​Hosted page

​Background

​Guarded action

​What the token contains

​Your rule

​Facts

​Dashboard settings

​Verifiers

Hosted page

Background

Guarded action

What the token contains

Your rule

Facts

Dashboard settings

Verifiers