Royall Connect — connect a person's vault to your product and ask permission before you use their likeness. Read the partner integration guide →

The authorization API for human likeness

Products

Five partner surfaces, one platform. Herald is documented in full on this page; Royall Connect, the detections feed, voice matching and the song catalogue are specified in the partner integration guide.

Sentinel

Sentinel is Royall's monitoring layer. A creator captures their likeness — voice, face, body — in their Royall vault, and Sentinel watches platforms for it from there. Nothing outward happens on a match by default: detections land in the creator's own inbox. Nothing is ever filed on a match alone — a filing is either made by the creator, or sent automatically only where that creator has signed a standing sworn authorization in advance.

Quickstart

The same call in every language. Pick your language once (left) and every snippet on this page follows.

# set your key once — never inline a secret in a shell history
export ROYALL_HERALD_KEY="rh_live_..."

curl -sX POST https://vault.royall.ai/v1/authorize \
  -H "Authorization: Bearer $ROYALL_HERALD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_code":"RYL-V-2026-DEM0V01C-8","use_case":"ads","depth":"synthesis"}'

# -> {"status":"ALLOW","tier":"commercial_synthesis","grant_id":"grant_…","signed_token":"…", ...}
# -> or {"status":"BLOCK","reason":"block:no_offer:commercial_synthesis/ads"}   (BLOCK is HTTP 200, not an error)

# Royall Python SDK — not on a package registry yet; we send you the source (see "SDKs" below). The API is plain HTTP; an SDK is optional.
from royall_herald import HeraldClient

herald = HeraldClient(api_key="rh_live_...")   # base_url defaults to vault.royall.ai

d = herald.authorize("RYL-V-2026-DEM0V01C-8", use_case="ads", depth="synthesis")
if d.allowed:                       # BLOCK is a normal result, not an exception
    proof = d.signed_token
else:
    print("blocked:", d.reason)

assert d.verify(herald.fetch_public_key())    # offline Ed25519 — zero callbacks

// Royall Node SDK — not on a package registry yet; we send you the source (see "SDKs" below). Zero dependencies; Web Crypto for verify.
import { HeraldClient } from "royall-herald";

const herald = new HeraldClient({ apiKey: "rh_live_..." });

const d = await herald.authorize("RYL-V-2026-DEM0V01C-8", "ads", { depth: "synthesis" });
if (d.allowed) {
  const proof = d.signedToken;
} else {
  console.log("blocked:", d.reason);
}

const ok = await d.verify(await herald.fetchPublicKeyRaw());   // offline

// Royall Go SDK — not on a package registry yet; we send you the source (see "SDKs" below). Package: herald. Standard library only.
c, _ := herald.NewClient(herald.Options{APIKey: "rh_live_..."})

d, err := c.Authorize(ctx, "RYL-V-2026-DEM0V01C-8", "ads",
    herald.AuthorizeOptions{Depth: "synthesis"})
if err != nil { /* auth(401) / rate-limit(429) / server(5xx) / network */ }
if d.Allowed() {              // BLOCK is not an error
    proof := d.SignedToken
} else {
    fmt.Println("blocked:", d.Reason)
}

pub, _ := c.FetchPublicKeyRaw(ctx)
ok := d.Verify(pub)                // offline crypto/ed25519

No key yet? Everything below works against the sandbox with an rh_test_ key — no live data required.

Authentication

Every request carries your Herald key as a bearer token:

Sandbox

Ask your Royall contact for an rh_test_ key to exercise the endpoint and the SDKs without a live asset, creator, or license. A sandbox key runs the real decision against a synthetic, fully-licensed asset, so your ALLOW/BLOCK handling exercises the real decision logic. Every response carries "sandbox": true. The asset_code you send is ignored — the synthetic menu is fixed:

# the demo Asset ID is optional — the decision always uses the synthetic menu
export ROYALL_HERALD_KEY="rh_test_..."
curl -sX POST https://vault.royall.ai/v1/authorize \
  -H "Authorization: Bearer $ROYALL_HERALD_KEY" -H "Content-Type: application/json" \
  -d '{"asset_code":"RYL-V-2026-SANDB0X0-N","use_case":"ads","depth":"synthesis"}'
# -> {"status":"ALLOW","tier":"commercial_synthesis","sandbox":true,"signed_token":"…", ...}

POST /v1/authorize

Decide + (on ALLOW) issue a signed grant. Both ALLOW and BLOCK return HTTP 200 — BLOCK is a valid answer, not an error. Read status.

Request body

Every block:* reason

Consent tiers

What a creator can authorize, from most-protected to most-permissive. Your use_case + depth resolve to exactly one tier; if the creator offered it (and your company holds any required license) you get ALLOW.

Creators may also attach exclusions — categories they won't allow regardless of tier: alcohol, gambling, tobacco, cannabis, adult, political, religious, competitors. A hit returns block:creator_exclusion:<category>.

The universal floor

The signed grant

On ALLOW, signed_token is a portable, Ed25519-signed proof-of-clearance binding the asset, tier, use, your company, a grant_id, and a short expiry (~15 min, ≤ 1 hour). Embed it in your output (e.g. as a C2PA assertion). Anyone can verify it offline against Royall's public key — every SDK's verify() does this with zero calls back to Royall, using a canonical-bytes derivation that's byte-identical across Python, Node, and Go.

Returns {alg:"ed25519", kid, public_key_pem, public_key_b64, signed_endpoints, c2pa_cert_chain_url}. Re-authorize at generation time — a short TTL means a withdrawn grant flips to BLOCK by architecture, not by polling.

The separate key for sandbox grants. Returns {alg:"ed25519", kid, public_key_b64, env:"sandbox", warning}; the kid is prefixed sbx-. For integration testing only — never load this key into a production verifier. Its whole purpose is that production cannot accept what it signs.

What verify() checks

In this order, failing closed at every step: signature present → the signed env selects which key must have signed it (an unrecognised or missing env is rejected, not assumed) → signature → principal parses → version == 4 (exact — reject anything else) → identity_verified is a real boolean → expiry → status == "ALLOW" → and finally, a sandbox grant is refused unless you explicitly opted in. The signature is checked before the environment is acted on, so a forged env cannot route around it.

What verify() does not check

A passing verify() proves Royall issued the grant. It does not prove the grant was issued to you, for this asset, or for this operation. Royall signs with one production key, so a valid grant belonging to another platform, another Asset ID or another use case passes every check above. verify() takes no caller expectation — after it passes, compare the signed claims to the values you expected:

Skipping this comparison makes the token a proof that somebody was authorized for something.

Resolver & badge

A Royall Asset ID is a public, printable handle (like a phone number). The code is public; what it resolves to is consent-gated.

Asset IDs look like RYL-V-2026-7K3F9Q2X-N — namespace · kind (V/F/B) · year · random designation · a Luhn-mod-32 check character. Case-insensitive and hyphen-tolerant.

Embed the badge

Drop a live “Verified Human by Royall” badge into your own product — it reflects the current consent status and links to the full /verify/{code} page. The badge is a cue, not proof: the authoritative check is the resolver + the signed grant, so the badge always links back to /verify.

Plain HTML — no JavaScript

Works anywhere an image does: a web page, a README, an email.

<a href="https://vault.royall.ai/verify/RYL-V-2026-7K3F9Q2X-N">
  <img src="https://vault.royall.ai/badge/RYL-V-2026-7K3F9Q2X-N.svg"
       alt="Verify with Royall" height="28">
</a>

Web component — live, one tag

A custom element that renders the badge (Shadow-DOM isolated) and links to /verify. Load the script once, then use <royall-badge> anywhere.

<script src="https://vault.royall.ai/badge.js" async></script>

<royall-badge code="RYL-V-2026-7K3F9Q2X-N"></royall-badge>

The SVG is short-cached (status is live). Endpoints: GET /badge/{code}.svg (the image) and GET /badge.js (the component). Both are public and need no key. Embed them as an image and a script tag — they do not send CORS headers, so a cross-origin fetch() is blocked (and is not how you would use them).

Errors & rate limits

• ALLOW / BLOCK are both 200. A BLOCK is a decision, not a failure — branch on status.
• 401 — bad/missing key (missing_bearer_token / invalid_key_format / invalid_or_revoked_key).
• 422 — a mistyped Asset ID at /id/{code} ({"error":"invalid_checksum"}).
• 429 — over quota (rate_limit_exceeded). /v1/authorize is limited per key over a rolling 24-hour window. Allowances are agreed per partner rather than published, so ask us for yours. The /v1/connect/* endpoints are charged to a per-partner daily budget, not to an IP. Respect the Retry-After header rather than hard-coding a delay.
• 5xx — transient; retry with backoff. The decision path holds no ML, so it stays fast.

SDKs

No SDK is required. Herald is one JSON endpoint over HTTPS — the curl tab above is the whole integration, and grant verification is standard Ed25519 you can do with any crypto library.

If you'd rather not write it yourself, we maintain three SDKs. Each gives you a typed authorize() returning a Decision (BLOCK is not an error) plus offline grant verify(). Canonical grant bytes are byte-identical across all three, so a grant signed for one verifies in the others.

These are not yet on public package registries. Ask your Royall contact and we'll send you the SDK for your language, or integrate directly against the HTTP endpoint above — both are fully supported.