Siteverify endpoint

curl --request POST \
  --url https://api.example.com/v1/siteverify

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/siteverify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/siteverify"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/siteverify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "success": true,
  "challenge_ts": "<string>",
  "hostname": {},
  "action": {},
  "cdata": {},
  "request_id": {},
  "verdict": "<string>",
  "challenged": true,
  "outcome": {},
  "test": true
}

POST

siteverify

Siteverify endpoint

curl --request POST \
  --url https://api.example.com/v1/siteverify

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/siteverify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/siteverify"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/siteverify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

{
  "success": true,
  "challenge_ts": "<string>",
  "hostname": {},
  "action": {},
  "cdata": {},
  "request_id": {},
  "verdict": "<string>",
  "challenged": true,
  "outcome": {},
  "test": true
}

Call siteverify from your backend with the token the challenge widget wrote into the heretic-response field. The request and the success / error-codes shape match Cloudflare Turnstile; the Heretic fields are added to the same object.

POST https://heretic.tech/v1/siteverify
Content-Type: application/json

{ "secret": "hrtc_sk_...", "response": "<heretic-response>" }

The secret key travels in the body, not in a header. application/x-www-form-urlencoded bodies are accepted with the same field names.

Request

Field	Meaning
`secret`	Your secret key (`hrtc_sk_` + 32 lowercase hex). Required.
`response`	The token from the `heretic-response` field. Required.
`idempotency_key`	Lets the same token verify again under the same key. Optional. See single use.
`remoteip`	Accepted for Turnstile compatibility. Not read. The address Heretic measured is in the assessment’s `record.client_ip`.

Status codes

Status	Body
`200`	A JSON object with `success: true` and the fields below, or `success: false` and `error-codes`. Verification failures are `200`, as in Turnstile.
`429`	`{ "success": false, "error-codes": ["rate-limited"] }` with a `retry-after` header in seconds.

Every response carries cache-control: no-store.

Success response

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

boolean

required

true. The token was signed by Heretic, belongs to a site of the tenant that owns secret, has not expired, and has not been used before under a different key.

string

required

UTC RFC 3339 time the token was issued. Tokens expire 300 seconds after this time. It is not the time the ceremony completed.

string | null

required

Host of the page the widget ran on. For a real site key it matches the site’s verified domain, its www. form, or a subdomain of it, because the widget mints no token otherwise. For a test token it is the host the page claimed, unverified. Compare it with your own domain.

string | null

required

The widget’s data-action when the token was issued without a ceremony. null when a ceremony ran: the ceremony token does not carry the action.

string | null

required

The widget’s data-cdata, up to 255 characters. When a ceremony ran, the same value: it was recorded as the ceremony’s account_ref and is returned from there.

string | null

required

Raw 32-character request ID of the assessment behind the token. Read it with the same secret key at GET /v1/verdict/{request_id} for signals, families, network, concealment, identity, and the client record. null for a test token.

string

required

uncontradicted, contradicted, or refused. Which values reach you depends on the widget’s data-escalate policy: a verdict the policy steps up never arrives without challenged: true. See which values each path returns.

boolean

required

true when the visitor completed a device ceremony before the token was issued.

string | null

required

passed when challenged is true, else null. No token is issued for a ceremony that ended contradicted or not_completed, so no other value occurs.

boolean

true only when secret is the reserved test secret. Absent otherwise.

What each path returns

Token issued by	`challenged`	`verdict`	`outcome`	`request_id`	`action`
Probe passed under the site’s `data-escalate` policy	`false`	The probe’s verdict: `uncontradicted`; also `contradicted` under `refused`; also `refused` under `never`	`null`	The probe assessment	`data-action`
Ceremony passed after a stepped-up probe	`true`	`contradicted`, whether the probe was `contradicted` or `refused`	`passed`	The assessment measured on the ceremony device. The stepped-up probe’s assessment is not carried.	`null`
The always-pass test site key	`false`	`uncontradicted`	`null`	`null`	`data-action`

A probe whose result never reached Heretic is treated as refused for the escalation decision.

Single use and idempotency

A token verifies once. A second call with the same token answers timeout-or-duplicate, whichever secret key presents it. Send idempotency_key when your handler can run twice for one submission, for example after a retry. The second call succeeds only when it presents the same key as the first; the response is computed from the token, so it is identical. A first call without a key cannot be repeated with one. A different key is a replay. Consumed tokens are remembered until their 300-second expiry, and expiry alone also answers timeout-or-duplicate.

Failure response

{ "success": false, "error-codes": ["invalid-input-response"] }

error-codes carries exactly one code.

Code	Status	Cause
`missing-input-secret`	`200`	`secret` absent or empty.
`invalid-input-secret`	`200`	`secret` malformed, unknown, or revoked.
`missing-input-response`	`200`	`response` absent or empty.
`invalid-input-response`	`200`	Token malformed, signed before a signing-key rotation, issued to another tenant’s site, or a test token presented to a real secret, or a real token presented to the test secret.
`timeout-or-duplicate`	`200`	Token older than 300 seconds, or already verified without a matching `idempotency_key`.
`bad-request`	`200`	Body is not JSON or form-encoded.
`internal-error`	`200`	A store Heretic needs did not answer. Retry with backoff, with the same `idempotency_key` if you sent one.
`rate-limited`	`429`	Your server’s address sent more than 600 secret-key requests in a minute across siteverify, challenge, verdict, and usage. `retry-after` names the wait in seconds.

Do not convert a failure into acceptance. A token Heretic cannot verify is no token.

Test secret

hrtc_sk_00000000000000000000000000000000 verifies only tokens minted by the always-pass test site key, answers with "test": true and request_id: null, and does not consume them. A real secret answers invalid-input-response to a test token. The keys are listed on the widget page.

Example

export async function verifyHereticToken(token, idempotencyKey) {
  const response = await fetch('https://heretic.tech/v1/siteverify', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      secret: process.env.HERETIC_SECRET_KEY,
      response: token,
      idempotency_key: idempotencyKey,
    }),
  });
  if (response.status === 429) throw new Error('Heretic siteverify rate-limited');
  const result = await response.json();
  if (!result.success) return { ok: false, code: result['error-codes'][0] };
  return {
    ok: true,
    hostname: result.hostname,
    verdict: result.verdict,
    challenged: result.challenged,
    requestId: result.request_id,
  };
}

result.request_id is the handle for everything else Heretic measured. Policy on the verdict, the record, and the identifiers is yours.

Get started

Collector

Challenge widget

Understand Heretic

Reference

Manage and troubleshoot

Siteverify endpoint

Request

Status codes

Success response

What each path returns

Single use and idempotency

Failure response

Test secret

Example

​Request

​Status codes

​Success response

​What each path returns

​Single use and idempotency

​Failure response

​Test secret

​Example

Request

Status codes

Success response

What each path returns

Single use and idempotency

Failure response

Test secret

Example