Clearance keys

curl --request GET \
  --url https://heretic.tech/v1/clearance/keys/{site_key}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/v1/clearance/keys/{site_key}",
  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/clearance/keys/{site_key}"

	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/clearance/keys/{site_key}")

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

clearance

keys

{site_key}

Clearance keys

curl --request GET \
  --url https://heretic.tech/v1/clearance/keys/{site_key}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://heretic.tech/v1/clearance/keys/{site_key}",
  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/clearance/keys/{site_key}"

	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/clearance/keys/{site_key}")

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

Public. No secret is required. Verify a clearance against these keys on your server or edge.

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "kid": "site_0123456789abcdef01234567/1",
      "x": "<base64url>",
      "alg": "EdDSA",
      "use": "sig"
    }
  ]
}

kid matches the token header. x is the raw Ed25519 public key. The response carries cache-control: public, max-age=300. Cache keys by kid.

Status codes

Code	Cause
`404`	Unknown or revoked site key.
`403`	`site-unverified`. The site’s domain is not verified.

Rotation

Rotate signing key on the site’s dashboard panel increments the key version. New tokens carry the new kid. The response lists the current and the previous version, so a token signed before rotation verifies until it expires.

Verify

Node with jose:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://heretic.tech/v1/clearance/keys/hrtc_live_…'));

const { payload } = await jwtVerify(jwt, JWKS, {
  issuer: 'https://heretic.tech', audience: 'shop.example', algorithms: ['EdDSA'],
});

Python with PyJWT and cryptography:

import jwt

jwks = jwt.PyJWKClient("https://heretic.tech/v1/clearance/keys/hrtc_live_…")

key = jwks.get_signing_key_from_jwt(token)
payload = jwt.decode(token, key.key, algorithms=["EdDSA"],
                     audience="shop.example", issuer="https://heretic.tech")

PHP with firebase/php-jwt. The library checks exp; check iss and aud yourself.

use Firebase\JWT\JWT;
use Firebase\JWT\JWK;

$jwks = json_decode(file_get_contents('https://heretic.tech/v1/clearance/keys/hrtc_live_…'), true);
$payload = JWT::decode($jwt, JWK::parseKeySet($jwks, 'EdDSA'));
if ($payload->iss !== 'https://heretic.tech' || $payload->aud !== 'shop.example') {
    // refuse
}

Cloudflare Workers with WebCrypto and no library:

const b64u = (s) => Uint8Array.from(atob(s.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
const json = (s) => JSON.parse(new TextDecoder().decode(b64u(s)));

async function verifyClearance(jwt, siteKey, domain) {
  const [h, p, s] = jwt.split('.');
  const header = json(h);
  if (header.alg !== 'EdDSA') return null;
  const { keys } = await (await fetch(`https://heretic.tech/v1/clearance/keys/${siteKey}`)).json();
  const jwk = keys.find((k) => k.kid === header.kid);
  if (!jwk) return null;
  const key = await crypto.subtle.importKey('jwk', { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, { name: 'Ed25519' }, false, ['verify']);
  const ok = await crypto.subtle.verify('Ed25519', key, b64u(s), new TextEncoder().encode(`${h}.${p}`));
  if (!ok) return null;
  const payload = json(p);
  const now = Math.floor(Date.now() / 1000);
  if (payload.iss !== 'https://heretic.tech' || payload.aud !== domain || payload.exp <= now) return null;
  return payload;
}

Then apply your rule.

Get started

Collector

Challenge widget

Clearance

Frameworks and server clients

Understand Heretic

Reference

Manage and troubleshoot

Clearance keys

Status codes

Rotation

Verify

​Status codes

​Rotation

​Verify

Status codes

Rotation

Verify