Challenge widget

The widget runs a browser check when it loads. By default, an uncontradicted result returns a token without interaction. A contradicted or refused result requires a phone challenge before a token is issued. Your server verifies the token before accepting the form.

Before you start

Create an account or sign in and create a site with the domain your form is served from.
Verify the domain using the instructions below.
Take the site key (hrtc_live_…) for the page and issue a secret key (hrtc_sk_…) for your server.

Use the test keys to check your form integration before creating an account.

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

<form action="/signup" method="POST">
  <div class="heretic-guard" data-sitekey="hrtc_live_0123456789abcdef01234567"></div>
  <button type="submit">Create account</button>
</form>

On success the widget writes a token into a hidden heretic-response field in the form. On a phone the ceremony runs inline. On a desktop it shows a QR code that continues on a phone.

Verify your domain

In the dashboard, open the site, set its domain, and publish the token it gives you in one of two places:

Method	Where	Value
DNS	`TXT` record at `_heretic.<your-domain>`	`heretic-site-verification=<token>`
File	`https://<your-domain>/.well-known/heretic-site-verification`	the token as the whole body

Then press Check now. A verified site accepts its domain and subdomains. Changing the domain requires verification again. Until then the widget reports site-unverified and issues no token.

Configure

Attribute	Meaning
`data-sitekey`	Site key. Required.
`data-theme`	`auto` follows the page preference; `dark` or `light` selects the widget shell. The ceremony uses its own dark appearance.
`data-size`	`normal` is 300 px wide; `compact` is 240 px; `flexible` fills its container.
`data-language`	`auto` follows the browser language. `en` and `es` select English or Spanish for the widget and ceremony. Other languages use English.
`data-mode`	`auto` (default) probes and escalates by `data-escalate`. `challenge` always runs the ceremony.
`data-escalate`	Which probe results trigger a ceremony. `contradicted` (default) steps up contradicted and refused. `refused` steps up only refused. `always`. `never`.
`data-escalate-concealed`	`true` also requests a challenge when the probe reports concealment indicators. Default `false`.
`data-action`	A label returned by siteverify.
`data-cdata`	Opaque data returned by siteverify, up to 255 characters.
`data-callback`	Global function called with the token and `{ challenged }`.
`data-error-callback`	Global function called with an error code.
`data-expired-callback`	Global function called when the proof expires, 300 seconds after the probe opened or the ceremony completed. The hidden field is cleared.
`data-response-field-name`	Hidden input name. Default `heretic-response`.
`data-clearance`	`true` also issues a clearance JWT.
`data-clearance-callback`	Global function called with the clearance JWT.

Challenge concealed connections

Concealment indicators are reported separately from the verdict. An uncontradicted probe can still report concealment, so this setting is independent of data-escalate. Enable this option when your policy requires a challenge for a connection with concealment indicators.

<div class="heretic-guard"
     data-sitekey="hrtc_live_0123456789abcdef01234567"
     data-escalate-concealed="true"></div>

A ceremony with detected concealment stays pending and asks the visitor to disable the VPN, proxy, or relay. The visitor can retry before the original expiry. See what a pass means. The widget also requests a challenge if the probe cannot be read. data-cdata correlates the result with an attempt in your application. It never selects a passkey account. Use the authenticated challenge API with account_ref for account-bound authentication.

Script API

const id = heretic.render('#guard', {
  sitekey: 'hrtc_live_…', theme: 'auto', size: 'normal', language: 'en',
  callback: (token) => {},
});

heretic.getResponse(id), heretic.getClearance(id), heretic.reset(id), heretic.remove(id), heretic.execute(id), heretic.isExpired(id). heretic.challenge(url) opens a ceremony minted by the challenge API. A page that also loads the collector keeps one heretic name: heretic({ siteKey }) runs the probe and heretic.render(...) runs the widget, whichever script loads first.

Test keys

Key	Behaviour
`hrtc_live_000000000000000000000000`	Always passes. A token arrives at once, no probe, no ceremony.
`hrtc_live_000000000000000000000001`	Always fails. `data-error-callback` receives `test-fail`.
`hrtc_sk_00000000000000000000000000000000`	Secret for siteverify. Accepts only tokens from the passing key, answers `"test": true`, and does not consume them.

A real secret never accepts a test token. To exercise the ceremony itself, use a real site key with data-mode="challenge".

Verify on your server

curl https://heretic.tech/v1/siteverify \
  -H "content-type: application/json" \
  -d '{"secret":"hrtc_sk_your_secret_key","response":"<heretic-response>"}'

{
  "success": true,
  "hostname": "casino.example",
  "request_id": "0123456789abcdef0123456789abcdef",
  "verdict": "uncontradicted",
  "challenged": false,
  "outcome": null
}

Send expected_hostname, expected_action, and expected_cdata from your server session, and require success === true. Use policy: "challenge" with challenge-only mode and reject_concealed: true when your backend requires no observed concealment. Browser attributes cannot enforce your backend policy. request_id reads the full assessment at GET /v1/verdict. Each probe or completed ceremony supplies one single-use proof, expiring 300 seconds after the probe opened or the ceremony completed. Repeating a token exchange does not renew it. Every field and error code is on the siteverify page. Node, Python and PHP clients implement siteverify, verdict reads and challenge calls. The plain HTML guide includes a complete form and backend.

Content security policy

script-src https://heretic.tech;
frame-src  https://heretic.tech;

For the heretic.challenge(url) modal, also allow https://heretic.tech in style-src so its external guard.css can load. The modal supports keyboard focus containment, Escape dismissal when allowed, and focus return.

Limits

60 widget calls a minute per visitor address, 1,200 decisions a minute per site, and 500 ceremonies open per account. Over a limit the widget reports 429 through data-error-callback. The widget counts one probe per visitor and one challenge per ceremony against your plan. Sandbox stops at its limit and the widget reports quota-exceeded.

Get started

Application integration

Collector