Skip to content

Authorisation Stamps

Until now the proof that an agent's action was authorised lived in your Provenance Vault and in the receipts you export. An Authorisation Stamp is that proof travelling with the action itself. When an agent sends an email, posts to an API, submits a payment instruction or produces a document, the artefact carries a compact signed stamp. Whoever receives it, a bank, a supplier, a counterparty's agent, a regulator, checks it in one call or fully offline against your published key, with no account and no trust in Xybern's database, and sees: authorised, under which Charter version, on the authority of an accountable human, within which bounds, by which agent, when, and not substituted since.

Receivers create the demand. A bank that says "we refuse agent-initiated instructions without a valid authorisation stamp" makes every organisation sending agents at it an issuer. The checker is free and universal; the issuer is the product.

Sender: in one minute

Turn stamps on for the workspace (Stamps view, "Stamps enabled", or POST /v1/enforce/stamps/settings {"enabled": true}). From then on every authorised outbound action (send_*, pay*, payment*, transfer*, publish*, post_*, external_*, email*, notify*, submit*, issue_*) returns a stamp with the decision:

from xybern import Xybern
from xybern.stamps import http_headers, attach_email, payment_reference

client = Xybern(api_key="xb_live_...")
d = client.intercept("send_payment", "Refund 120 to #4411", agent_id="agt_payments", metadata={"amount": 120})
if d["decision"] == "allow":
    token = d["stamp"]["token"]                       # xst1.…
    requests.post(bank_url, json=payload, headers=http_headers(token))

Bind the stamp to the exact artefact when you have it, so a substituted artefact fails the check:

body = render_email(...)
d = client.intercept("send_email", body, agent_id="agt_support", stamp=True,
                     artefact_sha256=hashlib.sha256(body.encode()).hexdigest())
attach_email(msg, d["stamp"]["token"], footer=True)   # X-Xybern-Authorisation header + one-line footer

Or stamp later: client.stamp_decision(decision_id, artefact_sha256=...). Ask for a stamp on any authorised action with stamp=True; suppress one with stamp=False. A per-agent override is delegation_policy.stamp.

Where a rail cannot carry the token (ISO 20022 remittance information is 140 characters), send payment_reference(token), the resolver URL of the stamp; the receiver resolves it and gets the full stamp back.

Receiver: in one minute

Anyone, no account:

  • Browser: paste the stamp at https://xybern.com/check (or the issuer's own host). The signature is checked in the browser against the issuer's published key; the resolver reports whether the stamp still stands.
  • One call: GET <resolver>/<stamp_id> (the resolver is named inside the stamp), JSON or HTML.
  • Fully offline: fetch the issuer record once (<host>/.well-known/xybern-issuer/<issuer_id>), cache the keys, then
from xybern.stamps import verify_offline, verify
res = verify_offline(token, keys, artefact_sha256=sha256_of_what_you_received)
res["valid"], res["body"]["decision"]["outcome"], res["body"]["charter_hash"], res["body"]["accountable"]
verify(token)          # keys from the issuer record, then the resolver for revocation state

python -m xybern.stamps "$TOKEN" --artefact received.pdf
python tools/xybern-verify/verify.py --stamp "$TOKEN" --keys keys.json --artefact received.pdf

If the receiver also runs Xybern, its own Charter can require stamps on what it receives: declare "refuse any received payment instruction that does not carry a valid authorisation stamp from a trusted issuer" and the compiler emits an inbound_stamp rule; or add the rule directly. Trusted issuers are set in the Stamps view (* for any issuer). When the sender's issuer is on the same install, the receiver's decision is sealed in the sender's vault too (stamp_honoured), so both sides hold the record.

What a stamp reveals, and what it does not

It reveals the outcome, the action type, when it was decided, the issuer, the Charter version hash, a pseudonymous accountable-party id, the agent id, the bounds the agent was under, and the artefact hash. It never carries the action content, the metadata, a name or an email. The issuer resolves the accountable id to the human on lawful request (Stamps view, or GET /enforcement/stamps/accountable/<id>).

Revocation

Revoking a stamp (Stamps view, POST /v1/enforce/stamps/<id>/revoke) tells receivers to stop honouring it; Revoke everywhere on an agent revokes its outstanding stamps. The receipt remains the historical proof that the action was authorised at the time. Every issue, check and revocation is sealed to the Provenance Vault, and the resolver counts checks and honours.

Issuer identity

Your issuer id is your workspace id; your display name and trusted issuers are set in the Stamps view. Your issuer record is served at /.well-known/xybern-issuer/<id> on your host (a Sovereign install serves its own, so receivers can pin it directly), and you can opt into the public mirror at /.well-known/xybern-issuers. Keys are the Provenance Vault's published signing keys; retired keys stay published so older stamps still verify.

API

Method Path Purpose
POST /v1/enforce/stamps Issue for a decision: {decision_id, artefact_sha256?}
GET /v1/enforce/stamps List (agent_id, status, decision_id)
GET /v1/enforce/stamps/<id> One stamp, with its token while active
POST /v1/enforce/stamps/<id>/revoke Revoke
POST /v1/enforce/stamps/verify Issuer-side check of a token
GET, POST /v1/enforce/stamps/settings enabled, public_issuer, trusted_issuers, display_name
GET /proof/stamp/<id> Public resolver (no auth)
POST /check/verify, GET /check Public check endpoint and page
GET /.well-known/xybern-issuer/<id>, /.well-known/xybern-issuers Issuer record and public mirror

SDK 2.6.0: intercept(stamp=, artefact_sha256=), stamp_decision, list_stamps, get_stamp, revoke_stamp, verify_stamp, stamp_settings, and xybern.stamps. JavaScript 1.20.0: stampDecision, listStamps, getStamp, revokeStamp, verifyStamp, verifyStampOffline, stampHeaders, paymentReference. Format: Authorisation Stamp v1.