Create a challenge

curl --request POST \
  --url https://heretic.tech/v1/challenge \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mode": "<string>",
  "account_ref": "<string>",
  "ttl_s": 123
}
'

import requests

url = "https://heretic.tech/v1/challenge"

payload = {
    "mode": "<string>",
    "account_ref": "<string>",
    "ttl_s": 123
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({mode: '<string>', account_ref: '<string>', ttl_s: 123})
};

fetch('https://heretic.tech/v1/challenge', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/v1/challenge",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'mode' => '<string>',
    'account_ref' => '<string>',
    'ttl_s' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://heretic.tech/v1/challenge"

	payload := strings.NewReader("{\n  \"mode\": \"<string>\",\n  \"account_ref\": \"<string>\",\n  \"ttl_s\": 123\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://heretic.tech/v1/challenge")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mode\": \"<string>\",\n  \"account_ref\": \"<string>\",\n  \"ttl_s\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://heretic.tech/v1/challenge")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mode\": \"<string>\",\n  \"account_ref\": \"<string>\",\n  \"ttl_s\": 123\n}"

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

POST

challenge

Create a challenge

curl --request POST \
  --url https://heretic.tech/v1/challenge \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "mode": "<string>",
  "account_ref": "<string>",
  "ttl_s": 123
}
'

import requests

url = "https://heretic.tech/v1/challenge"

payload = {
    "mode": "<string>",
    "account_ref": "<string>",
    "ttl_s": 123
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({mode: '<string>', account_ref: '<string>', ttl_s: 123})
};

fetch('https://heretic.tech/v1/challenge', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/v1/challenge",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'mode' => '<string>',
    'account_ref' => '<string>',
    'ttl_s' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://heretic.tech/v1/challenge"

	payload := strings.NewReader("{\n  \"mode\": \"<string>\",\n  \"account_ref\": \"<string>\",\n  \"ttl_s\": 123\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://heretic.tech/v1/challenge")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"mode\": \"<string>\",\n  \"account_ref\": \"<string>\",\n  \"ttl_s\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://heretic.tech/v1/challenge")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"mode\": \"<string>\",\n  \"account_ref\": \"<string>\",\n  \"ttl_s\": 123\n}"

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

string

required

Bearer hrtc_sk_…

string

default:"phone"

phone, the default: the page runs the ceremony on the device that opens it. desktop: the page shows a QR code that hands off to a phone.

string

Your server-chosen account handle, up to 128 characters. An existing account asserts with one of its stored credentials. A new account registers a credential. Omit it for an anonymous ceremony. Widget cdata does not select an account.

integer

default:"600"

120 to 900.

Use this endpoint when your backend decides to request a phone challenge. The widget creates challenges automatically. Read the outcome at GET /v1/challenge/{challenge_id}.

Request

{ "mode": "phone", "account_ref": "acct-77", "ttl_s": 600 }

Response

{
  "api_version": "2",
  "challenge_id": "chg_0123456789abcdef0123456789abcdef",
  "url": "https://heretic.tech/challenge/<token>",
  "mode": "phone",
  "expires_at": "2026-09-01T12:10:00.000Z"
}

Save challenge_id with the pending action and its server session before returning the URL. Anyone with url can open this challenge. Keep it out of logs and analytics. A callback prompts your backend to read the saved challenge. It does not authorize the action. The first ceremony creates a passkey and then asks for a confirmation with that passkey. Later ceremonies for the same named account authenticate with a stored credential.

Show the ceremony

As a modal on your page. With guard.js loaded:

<script src="https://heretic.tech/guard.js"></script>
<script>
  heretic.challenge(minted.url, {
    language: 'en',               // en or es; other languages use English
    callback: (result) => {
      // { challenge_id, status, step_reached }
      location.href = '/signup/finish?challenge=' + result.challenge_id;
    },
    'dismiss-callback': () => {},   // visitor closed the frame; the ceremony stays pending
    dismissible: true,              // false removes Close and ignores Escape
  });
</script>

The frame closes when the ceremony reaches an outcome, then callback runs. On a phone the frame fills the screen. On a desktop it shows the QR hand-off and closes when the phone finishes. heretic.closeChallenge(id) closes it as a dismissal. In your own frame. Any origin may frame the page. Give the frame these permissions:

<iframe src="<url>" title="heretic verification"
  allow="publickey-credentials-get; publickey-credentials-create; accelerometer; gyroscope; magnetometer"></iframe>

At an outcome the page posts { source: "heretic", type: "heretic-challenge", challenge_id, status, step_reached } to its parent. Check event.origin === "https://heretic.tech". As a redirect. Send the visitor to url and bring them back yourself. Use the browser callback to notify your backend, then read the saved challenge ID before completing the action.

Status codes

Code	Meaning
`400`	Malformed body.
`401`	Bearer token missing or malformed.
`402`	Sandbox reached its monthly challenge allowance. Example: `{"error": "quota-exceeded", "plan": "sandbox", "used": 1000, "limit": 1000}`.
`404`	Unknown key, or a challenge that is not yours.
`429`	More than 600 calls a minute from your address. `retry-after` is set.
`503`	The challenge could not be created.

Creating a challenge does not consume a challenge unit. Usage starts once an accepted QR scan or explicit same-device Begin action initiates the attempt. Repeated scans and retries within the same challenge count once. See pricing.

Get started

Application integration

Collector

Challenge widget

Clearance

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Create a challenge

Request

Response

Show the ceremony

Status codes

​Request

​Response

​Show the ceremony

​Status codes

Request

Response

Show the ceremony

Status codes