Delegus API 0.2: 103 operations. Rendered from the API's OpenAPI document, which a test in the API's own suite checks against the live router, so this page and the service cannot disagree.
Availability. The production API at api.delegus.ai is serving. Sign up for a verify key: the sandbox is free with no card, and production starts with a 14-day free trial; the quickstart walks through your first signed decision.
Authentication. Bearer tokens. rpKey is a relying-party key and resolves to the RP DID; principalKey is issued to a company at onboarding; adminToken is Delegus's own. Public routes need none. Errors are { error, message }; a DENY is not an error, it is a signed receipt with HTTP 200.
v0.3-rc1, relying parties on delegus-base-v3 only: the dependencies this action must declare (D1). Each entry exactly { fingerprint, mode }, distinct. Pinned in the receipt as requires_hash = sha256(JCS(requires)) over the array as sent. Malformed: 400 REQUIREMENTS_MALFORMED; sent for a relying party on another profile: 400 REQUIREMENTS_NOT_SUPPORTED. Neither spends the Proof.
The Receipt, decision ALLOW or DENY. For a relying party on delegus-base-v3 (v0.3-rc1) the body also carries, beside the receipt and outside its signed payload: authority and authority_opening, capability_key_opening, relies_on and, on ALLOW, opening (spec §5.6).
Production checks need a plan for this account (error PLAN_REQUIRED). An access refusal before evaluation, like 401 or 429: no receipt and no DENY reason, and the proof is not spent. Sandbox checks are never refused this way.
The receipt for this decision would exceed the signer's 4,096-byte message limit (error RECEIPT_TOO_LARGE): the Grant's matching capability is too large (for example a very long resources list). Refused before the replay check: no receipt, the Proof is not spent. Narrow the capability.
Optional declaration: the authority the signer is about to sign (shown in the customer's console, cross-checked against receipts). Not the Grant bytes.
Choose key custody: delegus adds a Delegus-held key that signs only on a person's passkey approval; self retires Delegus's keys (they stay in the DID document)
Approve several prepared Grants with one passkey assertion over the bundle's challenge (the SHA-256 of their signing_input_hash values, sorted); Delegus then signs each Grant's exact bytes on its own, and each approval record carries the bundle, so each re-checks offline and each is revoked alone
ALREADY_APPROVED, PREPARATION_EXPIRED, APPROVER_DISABLED, PASSKEY_IN_USE, PERSON_PRESENT (the person is here; their simulated self cannot approve) or SIMULATED_RETIRED
Approve a prepared Grant with a person's passkey assertion; Delegus then signs exactly the prepared bytes and keeps the approval record (the assertion only as a hash)
ALREADY_APPROVED, PREPARATION_EXPIRED, APPROVER_DISABLED, PASSKEY_IN_USE, PERSON_PRESENT (the person is here; their simulated self cannot approve) or SIMULATED_RETIRED
List decisions, newest first, with filters and cursor pagination: a relying party's own, an org's relying parties, or any (admin)
Ordered by receipt_id descending. Receipt ids are ULIDs: time-ordered to the millisecond, arbitrary within one millisecond. Cursor pagination is stable under concurrent inserts.
org:admin keys: the member relying party named in the receipt (required for them). The ledger records that RP as reporter; the audit log records the org key that acted (action outcome.report).
v0.3-rc1: the entitled disclosure for a receipt (§R.5, §8), for its relying party or principal only
The dependency disclosure package, when the receipt declared dependencies: per relies_on entry, in declaration order, the dependency receipt and its opening (D2-D4, D6), transaction_equal (D5, Delegus's attestation) and, for CURRENT_AUTHORITY, the status credential read before P6 and the evidence nonce (D7 and evidence_commitment). The consumption snapshot, when the receipt pins one (evidence.consumption.snapshot_hash = sha256(JCS(consumption_snapshot))). The same 404 for an unknown receipt, a receipt with neither, and a caller not entitled to it.
Export decisions with their full receipts and outcome ledgers as NDJSON or CSV (same scope and filters as GET /decisions; up to 5000 rows per page, cursor in X-Delegus-Next-Cursor)
The service's default for new relying parties when omitted: delegus-base-v1 until the v0.3 launch, delegus-base-v3 after it. delegus-base-v3 before the launch is 409 V3_NOT_ENABLED; delegus-base-v2 is set by Delegus staff only (403 PROFILE_NOT_AVAILABLE), and so is an older profile once new relying parties default to delegus-base-v3.
v0.3-rc1: CLAIM_REQUIRED (a hosted relying party needs a verified domain claim of this org; a pending claim reserves nothing) or PROFILE_NOT_AVAILABLE (a profile set by Delegus staff only)
The service's default for new relying parties when omitted: delegus-base-v1 until the v0.3 launch, delegus-base-v3 after it. delegus-base-v3 before the launch is 409 V3_NOT_ENABLED; delegus-base-v2 is set by Delegus staff only (403 PROFILE_NOT_AVAILABLE), and so is an older profile once new relying parties default to delegus-base-v3.
Self-serve signup: provision an org, a managed relying party, its keys and a starter first ALLOW (console)
One call creates the org, a managed relying party (verified at creation), an org:admin key and the customer's first verify key, and mints a starter Grant and Proof so the customer's first /verify returns a signed ALLOW. The console should forward the end customer's IP in x-delegus-client-ip so the per-customer limit applies; the socket address is the console's own.
Parameters
Name
In
Type
Description
x-delegus-client-ip
header
string
The end customer's IP address, forwarded by the console.
Verify a fresh starter as the tenant's relying party and return the signed receipt
The one-click first receipt: runs a fresh starter through the real engine as the tenant's relying party and returns the signed ALLOW receipt, with no dependency on the customer running a command inside the proof window.
v0.3-rc1, relying parties on delegus-base-v3 only: the dependencies this action must declare (D1). Each entry exactly { fingerprint, mode }, distinct. Pinned in the receipt as requires_hash = sha256(JCS(requires)) over the array as sent. Malformed: 400 REQUIREMENTS_MALFORMED; sent for a relying party on another profile: 400 REQUIREMENTS_NOT_SUPPORTED. Neither spends the Proof.
Rotate and revoke API keys: self-service with any live key of the subject, or by admin with ?subject=<did>. A new key does not invalidate the old one; revoke explicitly.
Admin or org keys: act on this Principal or relying party instead of the caller's own subject (org keys: a member of the org; org:admin to issue or revoke).
Admin or org keys: act on this Principal or relying party instead of the caller's own subject (org keys: a member of the org; org:admin to issue or revoke).
Verify counts per UTC day, for metering and billing. An RP key sees its own verifies, a Principal key the verifies against its Grants, admin any subject.
only verifies made with this relying-party API key
by
query
"key" | "principal"
key: break each day down by the API key; principal: by the Principal whose Grant was checked (per-customer attribution for a relying party; unattributed = the Grant did not parse or verify)
Organizations: customer accounts owning Principals and relying parties, with org-scoped API keys (roles read and admin) for dashboards. Human identity lives in the console, never here.
Set an org's production entitlement: allowed or blocked, until when, and a check cap (console, admin)
The console owns plan state and pushes one fact per org on every change. A push whose as_of is older than the stored row's is ignored (applied false), so pushes may arrive out of order. Production /verify calls from an org without a current plan are refused with 402 PLAN_REQUIRED once enforcement is on; sandbox checks and comp tenants are never refused.
Signed daily Merkle roots (RFC 6962, SHA-256) over the receipt ids issued each UTC day, chained day to day and signed with the status key named in the service DID document. Leaf = SHA-256(0x00 ‖ receipt_id); node = SHA-256(0x01 ‖ left ‖ right). Anyone recomputes a root from the published leaf hashes; a receipt holder proves inclusion of their receipt id. Also served on status.<domain>/checkpoints/… .
OpenID AuthZEN Authorization API 1.0 Access Evaluation, shaped over /verify for Policy Enforcement Points such as MCP servers and gateways (COAZ-MCP binding). Same receipts, ledger and limits as /verify; fail closed.
type "agent", id = the Agent's did:key; properties.grant and properties.proof = the compact JWS the Agent presented (context.grant/proof also accepted)
actionrequired
object
Field
Type
Description
namerequired
"commerce:purchase" | "api:call"
properties
object
the remaining Delegus Action fields: amount, currency (commerce:purchase) or method (api:call); never type or resource
Production checks need a plan for this account (error PLAN_REQUIRED). An access refusal before evaluation, like 401 or 429: no receipt and no DENY reason, and the proof is not spent. Sandbox checks are never refused this way.
The receipt for this decision would exceed the signer's 4,096-byte message limit (error RECEIPT_TOO_LARGE): the Grant's matching capability is too large (for example a very long resources list). Refused before the replay check: no receipt, the Proof is not spent. Narrow the capability.
Aggregate service metrics. GET /metrics is public and per-subject-free (HQ finance dashboard, public metrics page). Observer keys read /decisions/stats and /usage service-wide for a staff-only collector without the admin token.
Hosted conformance runner: the published vectors run against an implementer endpoint (wire contract in @delegus/conformance). Reports are pinned to the vector-set hash and unsigned.
Start a hosted conformance run: the published vectors against your endpoint
Runs every published vector (and the htu, jcs and jti sets the endpoint supports) against the submitted endpoint and reports pass or fail per vector. The runner only POSTs JSON to that one URL, through the SSRF-hardened outbound path (public addresses only, no redirects, size cap, per-request timeout), at most 60 requests and 2 minutes per run, one run at a time per account, 10 starts per hour per key. Returns 202 with the run; poll GET /conformance/runs/{run_id}.
An https endpoint that speaks the conformance wire contract (delegus-conformance-http v1, see @delegus/conformance): one JSON POST per call, op evaluate / describe / normalizeHtu / canonicalize / sha256 / isJti. Never a Delegus host.
The console records that the org's approved person signed in from a work address (owner, 5 Nov 2026: work email now, domain later). A free email provider is refused (400 FREE_EMAIL). Only the address's SHA-256 is kept. The proof admits the org to production while it has no verified domain and no other org has verified that domain; it is never reported as a verified domain.
Parameters
Name
In
Type
Description
org_idrequired
path
string
Request body
Field
Type
Description
emailrequired
string (email)
proven_atrequired
string (date-time)
Responses
Status
Body
Meaning
200
object
Recorded
400
—
Not an email address, or a free email provider (FREE_EMAIL)
v0.3-rc1 launch switch: move every relying party on one profile to another (dry run by default; one transaction; audited per relying party; reversible)
v0.3-rc1 launch step: turn production off for every org without a verified domain (Delegus-operated orgs excepted); dry run by default; audited; a report
Add, rename or disable an approver (the org admin decides who may approve)
Parameters
Name
In
Type
Description
org_idrequired
path
string
approver_idrequired
path
string
The console's id for the person; no email is kept
Request body
Field
Type
Description
namerequired
string
disabled
boolean
confirms_only
boolean
This person's passkey confirms their own acts only (confirmations); it never approves a Grant and never vouches for another passkey. Left out: unchanged.
A statement to confirm one step with a passkey (workspace.delete with subject the console's org id; change_order.approve or change_order.release with subject change_order:<id>; record.act with subject records.<type>.<verb>@<type>:<id>; record.acts with 2 to 4 such acts on one record, space-separated, and says, the sentence the person reads), and its one-time challenge (five minutes): the challenge is the SHA-256 of the statement
Parameters
Name
In
Type
Description
org_idrequired
path
string
approver_idrequired
path
string
The console's id for the person; no email is kept
Request body
Field
Type
Description
purposerequired
enum (7)
one of: workspace.delete, change_order.approve, change_order.release, record.act, record.acts, org.authority_table, org.delegation
subjectrequired
string
says
string
record.acts and org.authority_table only, and required there: the sentence the person reads before touching (naming each act, or what the table gives). It is part of the signed statement.
max length 300
rp_id
string
Which of this service's passkey relying parties the ceremony runs on; the first when left out. sim.dev.delegus.ai: a simulated person on the demo company confirms with their software passkey (the statement then says simulated: true; refused off the demo list, while the person is present, or when they have a passkey of their own).
Confirm the statement with the approver's passkey: single-use, unexpired, this org's and this approver's, the assertion over exactly the statement's challenge. Returns the confirmation record (kept by hash, private)
Parameters
Name
In
Type
Description
org_idrequired
path
string
approver_idrequired
path
string
The console's id for the person; no email is kept
Request body
Field
Type
Description
statementrequired
object
credential_idrequired
string
client_data_jsonrequired
string
authenticator_datarequired
string
signaturerequired
string
Responses
Status
Body
Meaning
200
object
{ confirmed: true, purpose, subject, record_hash, record }
type "agent", id = the Agent's did:key; properties.grant and properties.proof = the compact JWS the Agent presented (context.grant/proof also accepted)
actionrequired
object
Field
Type
Description
namerequired
"commerce:purchase" | "api:call"
properties
object
the remaining Delegus Action fields: amount, currency (commerce:purchase) or method (api:call); never type or resource
v0.3-rc1, relying parties on delegus-base-v3 only: what POST /verify returns beside the receipt (spec §5.6), so an AuthZEN caller can open the receipt's commitments and hand its ALLOWs on as dependencies. Members as on the /verify response: authority and authority_opening when the receipt pins authority_commitment; capability_key_opening when evidence.consumption pins capability_key_commitment; relies_on when the receipt pins relies_on_hash; opening { fingerprint, nonce } on ALLOW only. Absent for relying parties on other profiles.
commerce:purchase: maxAmount (integer, minor units), currency (ISO 4217). api:call: methods (uppercase HTTP methods). Unknown keys deny at P17. v0.3-rc1 (delegus-base-v3): commerce:quote, commerce:accept and commerce:fulfil take maxAmount and currency like a purchase; any Capability may carry budget { total?, perPeriod? { amount, period }, uses? } (spec §3.3).
passed: every vector, committed receipt and supplied set passed. failed: the report shows which did not. error: the endpoint was refused by the outbound policy (not public, not https) or the run was interrupted.
endpointrequired
string
created_atrequired
string (date-time)
finished_atrequired
string (date-time) | null
requestsrequired
integer
Requests sent to the endpoint (at most 60 per run).
vectorsrequired
object
Field
Type
Description
sha256required
string
sha256 over the vector set that ran (recompute with vectorSetHash()).
An https endpoint that speaks the conformance wire contract (delegus-conformance-http v1, see @delegus/conformance): one JSON POST per call, op evaluate / describe / normalizeHtu / canonicalize / sha256 / isJti. Never a Delegus host.
The relying-party key that made the verify; null before key tracking
action_typerequired
"commerce:purchase" | "api:call" | null
The Action the relying party submitted to /verify, as checked. Null when the action was malformed, for decisions recorded before actions were kept (production: before 2026-09-23 01:57 UTC), and for decisions older than 7 years (the action fields are cleared then; the receipt itself is kept).
amountrequired
integer | null
commerce:purchase: integer minor units of currency (JPY has 0 decimals, USD 2, KWD 3). Null otherwise.
currencyrequired
string | null
commerce:purchase: ISO 4217 code. Null otherwise.
resourcerequired
string | null
The action resource as submitted (a purchase resource or an api:call URI).
Optional declaration: the authority the signer is about to sign (shown in the customer's console, cross-checked against receipts). Not the Grant bytes.
What Delegus knows about a Grant: its id, Agent and status entry. The Grant itself (authority, validity) is signed by the Principal and reaches Delegus only inside a /verify; see the receipt's authority and expires_at.
consent to be named publicly (metrics page); default false, admin-set
standing
object
v0.3-rc1: Delegus's standing for this subject, shown to its own org and to staff only (never on the directory view). Not good: a relying party is refused before evaluation (403 RP_SUSPENDED); a principal's Grants are denied under delegus-base-v3 (ISSUER_NOT_TRUSTED).
What any relying party may know about a Principal: identity, verification state with dates, key history, DID-document snapshot. Never the verification token or org membership.
DENY reason codes in the order of spec §5.2 (protocol), then §5.3 (trust), then ISSUER_NOT_TRUSTED (T1 under delegus-trust-v3), then the v0.3 budget code (P21, T7) and dependency codes (D1-D7).
The Capability that authorized the action; null on DENY; absent before P3.
expires_at
string (date-time)
RFC 3339 UTC
evidencerequired
object
Field
Type
Description
issuer_resolution
object
Field
Type
Description
didrequired
string
pattern ^did:web:
did_document_hashrequired
string
The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).
pattern ^sha256:[0-9a-f]{64}$
resolved_atrequired
string (date-time)
RFC 3339 UTC
status
object
Field
Type
Description
credential_urlrequired
string (uri)
credential_hashrequired
string
The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).
pattern ^sha256:[0-9a-f]{64}$
valid_from
string (date-time)
RFC 3339 UTC
checked_atrequired
string (date-time)
RFC 3339 UTC
status_list_indexrequired
string
trust_config_versionrequired
string
trust_config_hashrequired
string
The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).
pattern ^sha256:[0-9a-f]{64}$
consumption
object
v0.3-rc1 (delegus-base-v2 and delegus-base-v3): the consumption evidence when the matched Capability has a budget, or P21 refused on one (spec §3.3.1, §6.2). snapshot_hash pins the consumption snapshot (private evidence: served to entitled parties by GET /decisions/{receipt_id}/disclosure, never by GET /evidence).
Field
Type
Description
snapshot_hashrequired
string
pattern ^sha256:[0-9a-f]{64}$
as_ofrequired
string (date-time)
capability_key_commitment
string
delegus-receipt-v2: the §R.6 commitment over the chosen Capability's ledger key; opened by capability_key_opening beside the receipt.
pattern ^sha256:[0-9a-f]{64}$
capability_index
integer
≥ 0
exhausted
"total" | "period" | "uses"
When P21 refused: the first budget dimension without headroom.
consumed
"consumed" | "exhausted" | "unavailable"
The T7 answer when the spend ran.
protocolrequired
object
Field
Type
Description
resultrequired
"PASS" | "FAIL"
profilerequired
"delegus-base-v1"
profile_hashrequired
string
The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).
Compact JWS, alg EdDSA, typ delegus-receipt+jwt, kid did:web:<domain>#receipt-<n>.
authority_commitment
string
delegus-receipt-v2 (v0.3-rc1; such receipts carry receipt_version "delegus-receipt-v2"), in the signed payload: the §R.6 commitment over the matched Capability; present when a Capability matched (ALLOW, or a DENY decided after P16). A v2 receipt never carries authority in plaintext; the Capability and its opening come beside the receipt (authority, authority_opening).
pattern ^sha256:[0-9a-f]{64}$
transaction
string
delegus-receipt-v2, in the signed payload, ALLOW only: this receipt's pairwise transaction handle (§R.3), an output, never an input.
pattern ^[A-Za-z0-9_-]{22}$
relies_on_hash
string
delegus-receipt-v2, in the signed payload: sha256 over UTF-8 of JCS(the relies_on entries with their per-entry results), when the Action declared dependencies; the entries come beside the receipt (relies_on).
pattern ^sha256:[0-9a-f]{64}$
requires_hash
string
delegus-receipt-v2, in the signed payload: sha256 over UTF-8 of JCS(requires) exactly as the relying party sent it (§5.1).
pattern ^sha256:[0-9a-f]{64}$
authority_opening
string
Beside the receipt, not in the signed payload (v0.3-rc1 §5.6): opens authority_commitment to authority. Present exactly when the receipt pins authority_commitment. For a v2 receipt, authority beside the receipt is the matched Capability in plaintext, unsigned.
pattern ^[A-Za-z0-9_-]{43}$
capability_key_opening
string
Beside the receipt, not in the signed payload: opens evidence.consumption.capability_key_commitment to the ledger key (recomputed from authority by an entitled party). Present exactly when that commitment is pinned.
pattern ^[A-Za-z0-9_-]{43}$
relies_on
object[]
Beside the receipt, not in the signed payload: the per-dependency results, in Action order, pinned by relies_on_hash. Each entry: fingerprint, mode, checks (D2–D7, true | false | "skipped"), and for CURRENT_AUTHORITY evidence_commitment (§R.4).
min items 1 · max items 8
Field
Type
Description
fingerprintrequired
string
pattern ^sha256:[0-9a-f]{64}$
moderequired
"PRIOR_DECISION" | "CURRENT_AUTHORITY"
checksrequired
object
evidence_commitment
string
pattern ^sha256:[0-9a-f]{64}$
opening
object
Beside the receipt, not in the signed payload, ALLOW only, returned only in this response and only to this relying party: the commitment to this receipt that a later Action may declare in relies_on, and its opening. Give a downstream agent the fingerprint, never the nonce (§R.2).
Protocol profile for /verify: delegus-base-v1 (v0.2) or delegus-base-v3 (v0.3-rc1: dependencies, receipt v2). delegus-base-v2 is retired and set by Delegus staff only.
standing
object
v0.3-rc1: Delegus's standing for this subject, shown to its own org and to staff only (never on the directory view). Not good: a relying party is refused before evaluation (403 RP_SUSPENDED); a principal's Grants are denied under delegus-base-v3 (ISSUER_NOT_TRUSTED).
The service's default for new relying parties when omitted: delegus-base-v1 until the v0.3 launch, delegus-base-v3 after it. delegus-base-v3 before the launch is 409 V3_NOT_ENABLED; delegus-base-v2 is set by Delegus staff only (403 PROFILE_NOT_AVAILABLE), and so is an older profile once new relying parties default to delegus-base-v3.
The service's default for new relying parties when omitted: delegus-base-v1 until the v0.3 launch, delegus-base-v3 after it. delegus-base-v3 before the launch is 409 V3_NOT_ENABLED; delegus-base-v2 is set by Delegus staff only (403 PROFILE_NOT_AVAILABLE), and so is an older profile once new relying parties default to delegus-base-v3.
A ready-to-verify sample: a Grant issued by the shared sandbox Principal to a one-time agent, and a Proof bound to this relying party. Bounded: a $50 limit, resource sandbox/**, a 1-hour Grant. POST grant, proof and action to /verify with the tenant's rp_verify_key for a signed ALLOW.
Field
Type
Description
grantrequired
string
Grant compact JWS (vc+jwt).
proofrequired
string
Proof compact JWS (delegus-proof+jwt), aud = this relying party.
actionrequired
object
The exact Action the Proof is bound to (a $10.00 sandbox purchase).
grant_idrequired
string
expires_atrequired
string (date-time)
When the Proof leaves the relying party's 300-second window; call /orgs/self-serve/starter for a fresh one.
verify_urlrequired
string (uri)
verify_curlrequired
string
A ready shell command for /verify; the literal <rp_verify_key> marks where the customer's key goes.
v0.3-rc1, relying parties on delegus-base-v3 only: the dependencies this action must declare (D1). Each entry exactly { fingerprint, mode }, distinct. Pinned in the receipt as requires_hash = sha256(JCS(requires)) over the array as sent. Malformed: 400 REQUIREMENTS_MALFORMED; sent for a relying party on another profile: 400 REQUIREMENTS_NOT_SUPPORTED. Neither spends the Proof.