1. Cerata
  2. Docs
  3. Receipts and tokens

Receipts and tokens

Every check returns a receipt: a signed, tamper-evident record of what was checked, under which rules, with which result. Anyone can verify it, without a Cerata account, and it never contains the action's content or the recipient's details.

What a receipt is

A receipt is a JSON Web Signature (RFC 7515) in compact form, signed with Ed25519 (alg: EdDSA, RFC 8037). Three base64url parts joined by dots:

The protected header has exactly three members, alg, typ and kid. Anything else makes the receipt invalid. Digests are sha256: plus 64 hex characters over the RFC 8785 canonical JSON, so member order never matters.

What it records

ClaimTypeAlwaysDescription
schemastringAlwaysAlways receipt/v1.
issstringAlwaysThe issuer, https://clearance-kohl.vercel.app.
iatintegerAlwaysWhen it was signed, epoch seconds. Keys are judged at this time.
as_ofstringAlwaysThe date the law was evaluated at.
actionobjectAlwaystype and digest: a SHA-256 commitment to the action, never the action itself.
facts_digeststringAlwaysA commitment to the facts that were checked.
jurisdictionsstring[]AlwaysThe places whose rules were applied.
decisionenumAlwaysclear, flag, hold or block.
rulesarrayAlwaysid, version, result and citations for each rule. Citations commit to the exact legal text relied on (source_sha256, quote_sha256) and say whether that version is current.
packobjectAlwaysThe signed rule set the check ran on: id, ver, manifest_sha256, signers.
decision_digeststringAlwaysA commitment to the decision.
reviewobjectSometimesHow the check was reviewed, when it was.
approver_of_recordobjectSometimesOn a reviewed decision: the person, or the standing policy, that approved it.
recommended_byobjectSometimesOn a reviewed decision: who recommended it.
relied_onarraySometimesStored qualifications the decision relied on.

Commitments, not content. A receipt holds digests of the action and facts, never the phone number, email, message or address. To prove what was checked, keep the facts you sent; their digest matches the receipt.

Verify a receipt

The quickest way is POST /v1/verify. It needs no API key, so auditors, partners and regulators can use it too. It checks the signature against the full key history and returns the verified claims.

curl https://clearance-kohl.vercel.app/v1/verify \
  -H "Content-Type: application/json" \
  -d '{"receipt": "eyJhbGciOiJFZERTQSIs…"}'
const res = await fetch('https://clearance-kohl.vercel.app/v1/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ receipt: check.receipt }),
});
const { valid, reason, claims } = await res.json();
if (!valid) throw new Error(`receipt does not verify: ${reason}`);
import requests

res = requests.post("https://clearance-kohl.vercel.app/v1/verify", json={"receipt": receipt}, timeout=10)
out = res.json()
if not out["valid"]:
    raise ValueError(f"receipt does not verify: {out.get('reason')}")
print(out["claims"]["decision"], out["claims"]["jurisdictions"])

A well-formed request for a receipt that doesn't verify returns 200, with valid: false and a reason. An empty or malformed body returns 400 with errors[].

Verify offline

You can also verify without calling Cerata at all. The signing keys are published, append-only, at https://clearance-kohl.vercel.app/.well-known/jwks-history.json: root keys, and online keys each certified by a root. To verify a receipt:

  1. Find the key named by the header's kid. An unknown key is invalid.
  2. Reject it if the key was revoked at or before the receipt's iat.
  3. Check the key's root certification against a root you trust, and that the certified details match the key exactly.
  4. Check that iat falls inside the key's certified window. Verification is against iat, never “now”, so old receipts stay valid after keys rotate.
  5. Verify the Ed25519 signature, with typ exactly clearance-receipt+jws.

The SDK does all five steps:

The TypeScript SDK is in private preview; ask us for access. Everything it does is a plain HTTPS call, so the HTTP examples work today from any language.

TypeScript
import { createClient } from '@cerata/sdk';

const cerata = createClient({
  apiKey: process.env.CERATA_API_KEY!,
  baseUrl: 'https://clearance-kohl.vercel.app',
  // Pin the root keys you trust instead of trusting the published list on first use.
  // trust: { roots: [{ kid: '…', jwk: { kty: 'OKP', crv: 'Ed25519', x: '…' } }] },
});

const result = await cerata.verifyReceipt(check.receipt);   // offline, against the key history
console.log(result);

Decoding is not verifying. Anyone can base64-decode a receipt and read its claims. Only the full key check above tells you it is genuine. If you write your own verifier, run it against the conformance vectors below.

Clearance tokens

A receipt is a record. A token is a permission slip. Add "token": {"aud": "<the receiving service>"} to a check (optionally with "single_use": true), and when the decision is clear the response carries a short-lived token (typ: clearance-token+jwt) bound to that exact action and that one audience. Flag, hold and block never produce a token.

ClaimTypeAlwaysDescription
audstringAlwaysThe receiving service, exactly as you asked for it in token.aud.
act_hashstringAlwaysSHA-256 of the exact action that cleared. A receiver recomputes it.
act_typestringAlwaysThe action type.
decisionstringAlwaysAlways clear.
iat, nbf, expintegerAlwaysIssued, not-before and expiry, epoch seconds. Tokens live 15 minutes at most; read exp rather than assuming a lifetime.
jtistringAlwaysUnique token id.
issstringAlwaysThe issuer, https://clearance-kohl.vercel.app.
substringSometimesSubject.
rcpt, rcpt_hashstringSometimesThe check's receipt id and a hash of the receipt, tying the token to its receipt.
pack_verstringSometimesVersion of the rule set that cleared it.
single_usebooleanSometimesWhen true, the token can only be redeemed online, once.

Pass the token to the service that performs the action. That service can refuse anything that wasn't checked: see receivers. To redeem a token once, call POST /v1/verify?consume=true with token, aud and action; the first valid redemption answers valid: true, consumed: true and every later one reason: already_consumed.

The action hash

act_hash is sha256: plus the hex SHA-256 of the canonical JSON of the action core: the preflight body without its token and agent members, with type set to action.type at the top level. A receiver computes it from the action it is about to perform and refuses the token if it differs.

Send only documented fields when you use tokens. Cerata hashes the facts it understood, so unknown fields are left out of act_hash. The receiver must hash exactly the same fields, or it will refuse the token with action_mismatch.

Action core
{
  "type": "outbound_text",
  "action": {
    "type": "outbound_text",
    "purpose": "telemarketing",
    "at": "2026-10-21T10:05:00-04:00",
    "automated": true
  },
  "sender": {
    "name": "Gulf Coast Motors"
  },
  "recipient": {
    "phone": "+18135550190",
    "address": {
      "line1": "601 E Kennedy Blvd",
      "city": "Tampa",
      "state": "FL",
      "zip": "33602"
    },
    "consent": {
      "type": "prior_express_written"
    },
    "dnc_registered": false,
    "prior_calls_24h": 0
  },
  "content": {
    "text": "Hi Maria, want me to book you a test drive this weekend? Reply STOP to opt out."
  }
}

The open format: receipt/v1

The receipt and token formats are an open specification, published under CC0-1.0 and Apache-2.0, so anyone can build a verifier or a receiver without asking us. It covers:

  • Encoding: compact JWS, EdDSA only, exact {alg, typ, kid} headers, RFC 8785 digests.
  • Domain separation: each signed kind has its own typ, so a token never verifies as a receipt.
  • The receipt and token payloads, the token lifetime cap and the act_hash rule.
  • The append-only key history and how to resolve a key at iat.
  • The receiver protocol and its error codes.
  • Conformance: an implementation conforms when it returns the expected result for every case in the vectors.

Machine-readable files: receipt JSON Schema, token JSON Schema and conformance vectors (16 cases: valid, rotated, revoked, forged, wrong header, unknown key, outside the key window, wrong signer and a token presented as a receipt).