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.
`429`	Rate limited; respect `Retry-After`.
`503`	Verification keys are temporarily unavailable.

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 previous version. Rotating again removes older versions from the JWKS. Wait at least 30 days between routine rotations to preserve the maximum lifetime of outstanding tokens. Cached keys may remain usable for five minutes; rotation is not immediate revocation.

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
}

For Cloudflare Workers, use the tested WebCrypto verifier and complete gate from the server examples. It checks signatures, issuer, audience, expiry, issue time, version and site key, bounds key requests and refuses malformed tokens. Configuration is in examples/cloudflare-worker/README.md. Then apply your rule. A valid signature is not an admission decision.

Get started

Application integration

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