Siteverify endpoint

curl --request POST \
  --url https://heretic.tech/v1/siteverify

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/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://heretic.tech/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://heretic.tech/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

POST

siteverify

Siteverify endpoint

curl --request POST \
  --url https://heretic.tech/v1/siteverify

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/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://heretic.tech/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://heretic.tech/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

Call this endpoint from your server before performing the protected action. A browser callback only supplies a token.

{
  "secret": "hrtc_sk_...",
  "response": "<heretic-response>",
  "expected_hostname": "shop.example",
  "expected_action": "signup",
  "expected_cdata": "<attempt ID from your server session>",
  "idempotency_key": "<same attempt ID>"
}

JSON and form-encoded bodies use the same fields. Keep the secret on your server.

Request

Field	Meaning
`secret`, `response`	Secret key and widget token. Required.
`policy`	`uncontradicted`, the default, accepts an uncontradicted probe or a passed ceremony. `challenge` requires a passed ceremony. `report` verifies the proof and returns any probe verdict for your own policy to evaluate.
`reject_concealed`	`true` also rejects a probe with concealment indicators. A passed ceremony has already cleared its path checks. Default `false`.
`expected_hostname`	Exact hostname your server expects.
`expected_action`	Exact action your server expects, such as `signup`.
`expected_cdata`	Exact attempt ID stored in your server session.
`expected_site_id`	Exact site ID your server expects. Useful when one secret serves several sites.
`idempotency_key`	Up to 128 characters. Allows a retry of the same token with the same verification fields.
`remoteip`	Accepted for compatibility and ignored. Read the measured address from the verdict or ceremony device.

Set the policy and expected values in your backend. Never copy them from the submitted form. The widget’s data-escalate and data-mode control its presentation; a browser can change them. Use policy: "challenge" with data-mode="challenge". Use reject_concealed: true with data-escalate-concealed="true" when your action requires that check. With policy: "report", success means the proof verified; your code must then evaluate verdict.

Response

{
  "success": true,
  "challenge_ts": "2026-09-05T01:15:49.000Z",
  "hostname": "shop.example",
  "action": "signup",
  "cdata": "attempt-7f3a",
  "site_id": "site_0123456789abcdef01234567",
  "request_id": "0123456789abcdef0123456789abcdef",
  "verdict": "uncontradicted",
  "challenged": false,
  "outcome": null,
  "challenge_id": null,
  "devices": null,
  "concealed": false
}

Field	Meaning
`challenge_ts`	When the probe opened or the ceremony completed. The proof expires 300 seconds later.
`hostname`, `action`, `cdata`, `site_id`	The context attached to the proof. Action and cdata are preserved through a ceremony.
`request_id`	The original customer probe. Read it at `GET /v1/verdict`. `null` if no probe was created.
`verdict`	The original probe’s `uncontradicted`, `contradicted`, or `refused` verdict. An unavailable probe is reported as `refused`.
`challenged`, `outcome`	`true` and `passed` after a passed ceremony. Otherwise `false` and `null`.
`challenge_id`	The ceremony ID when one ran. Your backend can read its findings.
`devices`	The ceremony’s measured devices, using tenant-scoped ceremony identifiers. `null` for a probe-only token.
`concealed`	Whether the probe showed concealment. `false` for a passed ceremony.
`test`	`true` only for the test secret. Test responses contain no real measurement.

Single use

Each probe or completed ceremony supplies one single-use proof. Repeating the browser’s token request does not create another use or extend its expiry. Reusing it returns timeout-or-duplicate. A retry succeeds only with the same token, idempotency_key, policy, and expected context as the first successful request. A mismatch does not consume the proof. An expired proof cannot be retried. Make the protected action idempotent too. Store the attempt ID under a unique constraint with the account creation or other write. A successful verification retry must return the existing action result.

Failures

{ "success": false, "error-codes": ["context-mismatch"] }

Verification failures use HTTP 200. Check success === true, not just the HTTP status. A 429 includes retry-after in seconds.

Code	Cause
`missing-input-secret`, `missing-input-response`	Required field absent.
`invalid-input-secret`	Secret malformed, unknown, or revoked.
`invalid-input-response`	Invalid signature, wrong purpose or tenant, archived or erased site, or test proof with a real secret.
`policy-mismatch`	The proof does not meet your backend policy.
`context-mismatch`	Hostname, action, cdata, or site differs from your backend’s expected value.
`timeout-or-duplicate`	Proof expired or already used.
`bad-request`	Invalid body or verification options.
`internal-error`	A required store did not answer. Retry the same request.
`rate-limited`	Request budget exceeded. HTTP `429`.

On a timeout, network error, or failed verification, keep the action pending or reject it. Do not continue as if verification passed.

Test secret

hrtc_sk_00000000000000000000000000000000 verifies only the always-pass test site key. It returns test: true and allows repeated verification. Test keys check your integration, not the measurement or ceremony policy.

Get started

Application integration

Collector

Challenge widget

Clearance

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Siteverify endpoint

Request

Response

Single use

Failures

Test secret

​Request

​Response

​Single use

​Failures

​Test secret

Request

Response

Single use

Failures

Test secret