Challenge widget

The challenge widget silently measures a visitor, lets a clean one through with no friction, and steps a suspicious one into a physical device ceremony before allowing the action. Your backend confirms the result with a single server-side call. If you have wired Cloudflare Turnstile before, this is the same shape. Load the script and drop a container into the form you want to guard.

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

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

The widget runs the probe, and on success writes a token into a hidden heretic-response field inside the form. When the visitor is contradicted, it presents the ceremony first — on a desktop it shows a rolling QR to continue on a phone; on a phone it runs the ritual inline — and writes the token once they pass.

Prove your domain

The site key is public, so the widget only serves pages on the domain the site is registered to, and only once you have proven you control that domain. In the dashboard, open the site, set its domain, and start verification. You get a token to publish in one of two places:

Method	Where	Value
DNS	A `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. Either proof is enough. A verified site accepts its domain, the www. form, and any subdomain. Changing the domain restarts verification. Until a site is verified the widget reports site-unverified through data-error-callback and issues no token.

Configure

Attributes on the container, or options to heretic.render().

Attribute	Meaning
`data-sitekey`	Your public site key (`hrtc_live_…`). Required.
`data-mode`	`auto` (probe, escalate only the suspicious — default) or `challenge` (always run the ceremony).
`data-escalate`	Which verdicts pass without a ceremony: `contradicted` (step up contradicted and refused — default), `refused` (step up only refused), `always`, `never`. You set the policy; Heretic states no opinion.
`data-action`	A label for this widget instance, returned by siteverify.
`data-cdata`	Opaque data you attach (e.g. an account reference), returned by siteverify.
`data-callback`	Name of a global function called with the token.
`data-error-callback`	Name of a global function called with an error code.
`data-response-field-name`	Hidden input name (default `heretic-response`).

Explicit rendering

<script src="https://heretic.tech/guard.js"></script>
<div id="guard"></div>
<script>
  const id = heretic.render('#guard', {
    sitekey: 'hrtc_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    callback: (token) => { /* enable submit, stash token */ },
  });
</script>

heretic.render(container, options) returns a widget id. Also available: heretic.getResponse(id), heretic.reset(id), heretic.remove(id), heretic.execute(id), heretic.isExpired(id).

Test keys

Build against the widget without a real site, a real device, or quota. These keys are reserved and never belong to a tenant.

Key	Behaviour
`hrtc_live_000000000000000000000000`	Site key that always passes: a token arrives at once, with no probe and no ceremony, whatever `data-mode` or `data-escalate` say.
`hrtc_live_000000000000000000000001`	Site key that always fails: `data-error-callback` receives `test-fail`.
`hrtc_sk_00000000000000000000000000000000`	Secret for siteverify. Accepts only tokens minted by the passing test key, returns `"test": true`, and does not consume them, so the same token verifies again.

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

Verify on your server

Never trust the token on the client. When the form arrives, exchange it:

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

Request parameters (JSON or application/x-www-form-urlencoded):

Field	Meaning
`secret`	Your secret key (`hrtc_sk_…`). Never send it to the browser.
`response`	The token from the `heretic-response` field.
`remoteip`	The visitor’s IP (optional).
`idempotency_key`	Re-verify the same token safely under this key (optional).

Success response:

{
  "success": true,
  "challenge_ts": "2026-09-02T21:15:49.000Z",
  "hostname": "casino.example",
  "action": "signup",
  "cdata": "account-7f3a",
  "verdict": "uncontradicted",
  "challenged": false,
  "outcome": null
}

verdict is the probe’s finding; challenged says whether a ceremony ran; outcome is the ceremony result (passed) when it did. Check hostname against your own domain, exactly as you would with any siteverify. Failure response:

{ "success": false, "error-codes": ["timeout-or-duplicate"] }

Error code	Cause
`missing-input-secret`	Secret key not provided.
`invalid-input-secret`	Secret key wrong or unknown.
`missing-input-response`	Token not provided.
`invalid-input-response`	Token invalid, malformed, or for another site.
`timeout-or-duplicate`	Token expired (over 5 minutes) or already used.
`bad-request`	Malformed request body.
`internal-error`	Transient server error; retry with backoff.
`rate-limited`	Your server’s address exceeded 600 verifications a minute. The response is a `429` with `retry-after`.

Notes

Tokens are single-use and valid for 5 minutes, like any challenge token.
The widget surface is budgeted: 60 calls a minute per visitor address, 1,200 decisions a minute per site across all addresses, and at most 500 ceremonies open per account at once. Over budget, the widget reports 429 through data-error-callback; a visitor who waits and retries is served. These are ceilings against floods, not quotas you will meet in ordinary use.
The site key is public and the widget endpoints are pinned to your site’s registered domain, so register the domain your form is served from.
The widget counts one probe per visitor and one challenge per ceremony against your plan. Read this month’s counts, limits, and overage at GET /v1/usage with your secret key. Sandbox stops at its limit: the sensor opens no more sessions for your sites and the widget reports 429 with quota-exceeded instead of minting a ceremony. Paid plans keep serving; the excess is overage at $0.0025 per probe and$ 0.025 per challenge.

Get started

Understand Heretic

Integrate

Reference

Manage and troubleshoot

Challenge widget

Add the widget

Prove your domain

Configure

Explicit rendering

Test keys

Verify on your server

Notes

​Add the widget

​Prove your domain

​Configure

​Explicit rendering

​Test keys

​Verify on your server

​Notes

Add the widget

Prove your domain

Configure

Explicit rendering

Test keys

Verify on your server

Notes