Read the outcome

curl --request GET \
  --url https://heretic.tech/v1/challenge/{challenge_id}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/v1/challenge/{challenge_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$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/challenge/{challenge_id}"

	req, _ := http.NewRequest("GET", 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/challenge/{challenge_id}")

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

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

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

GET

challenge

{challenge_id}

Read the outcome

curl --request GET \
  --url https://heretic.tech/v1/challenge/{challenge_id}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/v1/challenge/{challenge_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$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/challenge/{challenge_id}"

	req, _ := http.NewRequest("GET", 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/challenge/{challenge_id}")

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

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

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

Send Authorization: Bearer hrtc_sk_… from your backend. Read the challenge ID you saved when creating the challenge.

{
  "api_version": "2",
  "challenge_id": "chg_0123456789abcdef0123456789abcdef",
  "status": "passed",
  "step_reached": "completed",
  "findings": [],
  "mode": "phone",
  "account_ref": "acct-77",
  "request_id": null,
  "devices": {
    "ceremony": {
      "request_id": "9a1c33f0e5b74d2288c0af41d7e6b512",
      "client_ip": "203.0.113.7",
      "identity": {
        "instance": "4f2c…",
        "machine": "b81d…",
        "version": 3,
        "scope": "challenge-tenant-v1",
        "tier": { "instance": "conditional", "machine": "conditional" }
      },
      "network": { "asn": 5617, "country": "PL", "class": "access" },
      "concealment": { "indicators": [], "unchecked": [] }
    },
    "desktop": null
  },
  "created_at": "2026-09-05T01:00:00.000Z",
  "expires_at": "2026-09-05T01:10:00.000Z",
  "completed_at": "2026-09-05T01:01:12.000Z"
}

status is pending, passed, contradicted, or not_completed. account_ref repeats the reference your backend supplied. request_id is the original customer probe for a widget challenge, or null for a direct API challenge.

The devices

devices.ceremony is the phone that ran the ritual. devices.desktop is the computer that displayed the QR in a desktop hand-off. Devices are null before they have been measured. Ceremony identifiers are scoped to your tenant. Compare them only within the same identity.scope and identity.version. They use a different namespace from the collector’s site-key-scoped identifiers. Keep the original probe and ceremony records separately. Both identifier tiers are conditional. Equal inputs can produce equal identifiers on distinct devices. Deleting cookies or a passkey does not itself remove the measured inputs; changing those inputs can change the identifiers. Store matches as evidence for your signup policy. A ceremony device’s request ID belongs to the ceremony measurement. Its customer-readable record is this devices block. Use the top-level request_id to read the original customer probe through the verdict API.

What a pass means

A pass requires completed browser measurements, the recorded phone movement and workload, and a verified WebAuthn signature. No conclusive finding can contradict the ceremony. The visitor holds the phone level, keeps it steady during the workload, then holds it upright in landscape orientation. The signature binds the measurements to this challenge. The browser supplies the motion readings. WebAuthn verifies the origin, challenge, and user verification, but does not authenticate the motion sensor. Synthetic readings can satisfy the checks, and passkeys can sync between devices. A pass therefore does not establish a unique person or physical device. The rolling QR establishes a fresh hand-off. A code relayed within its freshness window can still arrive from another location. Network country is an address-range observation, not physical co-presence. A ceremony with observed concealment holds at path-concealed while status remains pending. The visitor can turn off the VPN or relay and retry within the original expiry. A passing ceremony has no detected concealment indicators; an undetected proxy remains possible. concealment.unchecked reports checks that did not run. First use requires two passkey prompts. The visitor creates a passkey, then confirms with it to sign the measurements. Later ceremonies for the same named account use one authentication prompt. Each prompt starts with a tap on Confirm, including inside an embedded widget.

Stops and findings

Step	Meaning
`motion-permission`	Motion access was declined.
`motion-idle`	Required motion readings did not arrive.
`tilt-timeout`, `rotate-timeout`	The required position was not held in time.
`evidence-measured`	The browser could not submit its measurements.
`measurement-recording`	A required measurement was missing, refused, stale, or unreadable.
`ceremony-excluded`	The authenticator reported an excluded credential.
`bytes-issued`, `ceremony`, `assertion-received`	The passkey step did not finish.

A pending ceremony expires as not_completed on the next read. Failed credential persistence cannot produce a pass.

Finding	Tier	Meaning
`ceremony.results-unsigned`	Absolute	WebAuthn verification or the signed evidence binding failed.
`ceremony.ritual-incomplete`	Composite	The signed evidence omitted the required format or measurements.
`ceremony.turn-unmeasured`	Composite	The recorded level-to-upright turn is absent from the motion stream.
`ceremony.duration-implausible`	Composite	The recording or server interval is too short for the required ritual.
`join.stale-frame`	Composite	The desktop hand-off used no valid fresh frame.
`ceremony.gravity-implausible`	Conditional	Mean acceleration magnitude is outside the held-phone check. Linear acceleration can also cause this.
`ceremony.environment-drift`	Conditional	Network or fingerprint inputs changed between measurements.
`join.geography-contradiction`, `join.address-mismatch`	Conditional	The two connections reported different network countries or addresses.
`ceremony.instant-assertion`	Conditional	The assertion arrived unusually soon after issuance.

Probe findings from the required legs are included too. An absolute or composite contradiction is conclusive. A refused required leg ends as not_completed unless the ceremony also contains an invalid signed assertion.

Use the outcome once

A completed outcome remains readable for inspection. Bind it to the pending action and consume its ID once in your own database transaction. Reading passed twice must not create two accounts. See complete the write once.

Status codes

401 means missing or malformed authentication. 404 means an unknown key or a challenge outside your tenant. 429 includes retry-after. 503 means a required store failed; keep the action pending or reject it. When stable rendering was available, each device identity also includes rendering: { version: 1, hash: "<64 hex>", tier: "conditional" }. This hash is scoped to the challenge tenant. It cannot be compared directly with the same device’s site-scoped probe hash. The object is absent when either rendering output is missing or unstable.

Get started

Application integration

Collector

Challenge widget

Clearance

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Read the outcome

The devices

What a pass means

Stops and findings

Use the outcome once

Status codes

​The devices

​What a pass means

​Stops and findings

​Use the outcome once

​Status codes

The devices

What a pass means

Stops and findings

Use the outcome once

Status codes