Liorith/Registry
GUIDE · LIORITH REGISTRY

Usage Guide

How the proof link flow works - from signing on your server to the user-visible verification result.

How it works

1
Sign
Your server calls signProof(siteId, host, secretKey) and redirects the user to the resulting URL (via proofToUrl()). Signing happens server-side so the secret key never leaves your server.
2
Verify
The Liorith Registry validates the HMAC-SHA256 signature, checks the nonce hasn't been consumed, confirms the timestamp is within 120 s, and verifies the host is in the site's allowed_domains.
3
Result
The user sees the verification result page showing your site's name, status, and canonical domain from the registry. Each proof link is single-use and expires after 120 seconds.

Proof URL

Generated by proofToUrl(params). The SDK builds and signs this automatically - you don't need to construct it manually.

URL format
https://registry.liorith.net/verify
  ?site=SITE_ID
  &host=example.com
  &ts=1719820800000
  &nonce=a3f8c2d1e0b4
  &sig=<hmac-sha256>
site
Your site ID from the Liorith Registry admin panel.
host
The domain making the request - must be in the site's allowed_domains list.
ts
Unix timestamp in milliseconds when the proof was signed. Accepted within ±30 s clock skew.
nonce
12-character random hex string. Consumed on first use to prevent replay attacks.
sig
HMAC-SHA256 of the message v1:{site}:{host}:{ts}:{nonce} using the site's secret key.

Endpoints

GETregistry.liorith.net/verify?site=…&host=…&ts=…&nonce=…&sig=…HTML result page
GETapi.registry.liorith.net/verify?site=…&host=…&ts=…&nonce=…&sig=…JSON result
GETapi.registry.liorith.net/check?domain=…JSON registry lookup

/verify on registry.liorith.net is the user-facing page. api.registry.liorith.net/verify returns the same data as JSON for programmatic use. api.registry.liorith.net/check looks up any domain without requiring a signed proof - useful for status badges and widgets.

Checking a domain with /check

Use api.registry.liorith.net/check when you want to display registry status without redirecting the user through a proof flow - for example in status badges, admin dashboards, or showing whether a domain is Liorith-verified inline.

fetch example
const res = await fetch(
  'https://api.registry.liorith.net/check?domain=example.com'
);
const data = await res.json();
// { result: 'verified_registry', status: 'active', site: { name: '…', id: '…' } }
// { result: 'unknown' }
// { result: 'blacklisted' }
verified_registry
Domain found in the registry. Check status for active / deprecated / inactive / former / suspended.
unknown
Domain is not registered with Liorith.
blacklisted
Domain is on the Liorith Blacklist - registry lookup is skipped.

Unlike /verify, this endpoint requires no signature or nonce - it is read-only and rate-limited. See Response Codes for the full reference.