API reference

Source openapi.json · sha256 3712582c3eaafdc0763b6ec345de4a5790cb28c01d06d022ce2f5431bc347c37 · servers https://api.delegus.ai https://api.dev.delegus.ai

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. The sandbox on this site runs on a development environment, where nothing is a production identity.

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.

Verify#

The one call a relying party makes (§5).

POST `/verify`#

rpKey

Evaluate a Grant, Proof and Action; returns the signed Receipt

Request body · `VerifyRequest`

Field	Type	Description
`grant` required	`string`	Grant compact JWS as received in Delegus-Grant.
`proof` required	`string`	Proof compact JWS as received in Delegus-Proof.
`action` required	`Action`

Responses

Status	Body	Meaning
`200`	`Receipt`	The Receipt, decision ALLOW or DENY
`400`	`Error`	Malformed envelope (strings inside it are the engine's business and yield a DENY receipt)
`401`	`Error`	Unknown or non-RP API key
`402`	`Error`	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.
`413`	`Error`	Body over 64 KB
`503`	`Error`	Backing service unavailable before or after evaluation

Principal#

Grant lifecycle, agents and keys; authenticated as the issuing Principal.

POST `/revoke`#

principalKey or orgKey

Revoke a Grant (§7); idempotent; success only once visible everywhere

Parameters

Name	In	Type	Description
`principal`	query	`DidWeb`	org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)

Request body · `RevokeRequest`

Field	Type	Description
`grant_id` required	`string`	pattern `^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$`

Responses

Status	Body	Meaning
`200`	`RevokeResponse`	OK
`400`	`Error`	Bad grant_id
`401`	`Error`	Not a Principal key
`404`	`Error`	Not this Principal's Grant
`503`	`Error`	Revocation recorded but not yet visible; retry

GET `/grants`#

principalKey or orgKey or adminToken

Grants allocated by a Principal (ids, agents, status entries, revocation), newest first

Parameters

Name	In	Type	Description
`principal`	query	`DidWeb`	org keys: one member Principal (default: all of them); admin: any
`agent`	query	`DidKey`
`state`	query	`"active"` \| `"revoked"`
`limit`	query	`integer`
`cursor`	query	`string`	next_cursor from the previous page

Responses

Status	Body	Meaning
`200`	`GrantList`	OK
`400`	`Error`	Bad filter
`401`	`Error`	Unauthorized
`404`	`Error`	Named Principal is not a member

POST `/grants`#

principalKey

Reserve a Grant id and its Delegus-signed status entry

Request body · `GrantAllocationRequest`

Field	Type	Description
`agent` required	`string`	pattern `^did:key:z6Mk`

Responses

Status	Body	Meaning
`201`	`GrantAllocation`	Allocated
`400`	`Error`	Bad agent DID
`401`	`Error`	Not a Principal key
`409`	`Error`	Agent is disabled

POST `/agents`#

principalKey or orgKey

Register an Agent (inventory; not consulted by /verify)

Parameters

Name	In	Type	Description
`principal`	query	`DidWeb`	org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)

Request body · `AgentRequest`

Field	Type	Description
`did` required	`string`	pattern `^did:key:z6Mk`

Responses

Status	Body	Meaning
`201`	`Agent`	Registered
`400`	`Error`	Bad DID
`401`	`Error`	Not a Principal key
`409`	`Error`	Already registered

POST `/agents/{did}/disable`#

principalKey or orgKey

Kill switch: revoke every Grant naming the Agent

Parameters

Name	In	Type	Description
`did` required	path	`string`
`principal`	query	`DidWeb`	org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)

Responses

Status	Body	Meaning
`200`	`AgentDisabled`	OK
`401`	`Error`	Not a Principal key
`404`	`Error`	Not this Principal's Agent

POST `/keys/{kid}/compromise`#

principalKey or orgKey

Mark a Principal key compromised (§11)

Parameters

Name	In	Type	Description
`kid` required	path	`string`	URL-encoded DID URL
`principal`	query	`DidWeb`	org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)

Responses

Status	Body	Meaning
`200`	`KeyCompromised`	OK
`401`	`Error`	Not a Principal key
`403`	`Error`	Not this Principal's key
`404`	`Error`	Unknown key

POST `/keys/{kid}/retire`#

principalKey or orgKey

Retire a Principal key (§11 rotation): existing Grants stay valid to validUntil; new Grants must use an active key

Parameters

Name	In	Type	Description
`kid` required	path	`string`	URL-encoded DID URL
`principal`	query	`DidWeb`	org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)

Responses

Status	Body	Meaning
`200`	`KeyRetired`	Retired (idempotent; a compromised key stays compromised)
`401`	`Error`	Not a Principal key
`403`	`Error`	Not this Principal's key
`404`	`Error`	Unknown key

GET `/principals`#

rpKey or principalKey or orgKey or adminToken

Principal directory: who is registered and verified, since when, with which keys (any live key or admin)

Parameters

Name	In	Type	Description
`kind`	query	`"managed"` \| `"hosted"`
`state`	query	`"verified"` \| `"unverified"`
`org_id`	query	`OrgId`	that org's keys or admin only
`limit`	query	`integer`
`cursor`	query	`DidWeb`	next_cursor from the previous page (ascending DID order)

Responses

Status	Body	Meaning
`200`	`PrincipalDirectory`	OK
`400`	`Error`	Bad filter
`401`	`Error`	No live key and no admin token
`403`	`Error`	org_id filter by a key of another subject

GET `/principals/{did}`#

principalKey or adminToken or orgKey or rpKey

Principal state: the full record with verification instructions for the Principal itself, its org and admin; the directory view for any other live key

Parameters

Name	In	Type	Description
`did` required	path	`string`

Responses

Status	Body	Meaning
`200`	`Principal` \| `PrincipalDirectoryEntry`	OK
`401`	`Error`	Unauthorized
`404`	`Error`	Unknown Principal

PATCH `/principals/{did}`#

adminToken

Set the public-naming consent flag (admin)

Parameters

Name	In	Type	Description
`did` required	path	`string`

Request body · `PrincipalNamingRequest`

Field	Type	Description
`may_be_named` required	`boolean`

Responses

Status	Body	Meaning
`200`	`Principal`	Updated
`400`	`Error`	Bad body
`401`	`Error`	Not admin
`404`	`Error`	Unknown Principal

POST `/principals/{did}/verify`#

principalKey or adminToken or orgKey

Run domain verification now

Parameters

Name	In	Type	Description
`did` required	path	`string`

Responses

Status	Body	Meaning
`200`	`Principal`	OK
`401`	`Error`	Unauthorized
`404`	`Error`	Unknown Principal

GET `/grants/{id}/consumption`#

principalKey or orgKey or rpKey or adminToken

Consumable Grants (v0.3): balances and consumption log of a Grant

Parameters

Name	In	Type	Description
`id` required	path	`GrantId`
`limit`	query	`integer`
`cursor`	query	`integer`	next_cursor from the previous page (a log version)

Responses

Status	Body	Meaning
`200`	`GrantConsumption`	OK
`400`	`Error`	Bad cursor
`401`	`Error`	Unauthorized
`404`	`Error`	Unknown Grant, or a key without access (RPs see Grants they have verified)

Decisions#

Receipts and Outcome Attestations (§9).

GET `/decisions`#

rpKey or orgKey or adminToken

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.

Parameters

Name	In	Type	Description
`since`	query	`string (date-time)`	evaluated_at ≥ since
`until`	query	`string (date-time)`	evaluated_at < until
`decision`	query	`"ALLOW"` \| `"DENY"`
`reason`	query	`ReasonCode`
`principal`	query	`DidWeb`
`grant_id`	query	`GrantId`
`limit`	query	`integer`
`cursor`	query	`string`	next_cursor from the previous page
`rp`	query	`DidWeb`	org keys: one member relying party (default: all of them); admin: any
`key_id`	query	`ApiKeyId`	only verifies made with this relying-party API key

Responses

Status	Body	Meaning
`200`	`DecisionList`	OK
`400`	`Error`	Bad filter
`401`	`Error`	No RP key, org key or admin token

GET `/decisions/{receipt_id}`#

rpKey or orgKey or adminToken

A receipt and its outcome ledger

Parameters

Name	In	Type	Description
`receipt_id` required	path	`string`
`rp`	query	`DidWeb`	org keys: one member relying party (default: all of them); admin: any

Responses

Status	Body	Meaning
`200`	`Decision`	OK
`401`	`Error`	No RP key, org key or admin token
`404`	`Error`	Not this RP's decision

POST `/decisions/{receipt_id}/outcomes`#

rpKey or orgKey

Append an Outcome Attestation (§9) (the RP’s own key, or its org’s org:admin key with ?subject=)

Parameters

Name	In	Type	Description
`receipt_id` required	path	`string`
`subject`	query	`DidWeb`	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).

Request body · `OutcomeEvent`

Field	Type	Description
`type` required	`enum (7)`	one of: `fulfilled`, `cancelled`, `dispute_opened`, `dispute_resolved`, `chargeback_received`, `chargeback_reversed`, `loss_reported`
`occurred_at` required	`string (date-time)`	RFC 3339 UTC
`evidence_ref`	`string`
`note`	`string`
`correction_of`	`string`	pattern `^oat_`
`reporter_signature`	`string`
`resolution`	`"agent_at_fault"` \| `"agent_not_at_fault"` \| `"indeterminate"`	required for dispute_resolved
`loss_amount`	`integer`	required for loss_reported; minor units ≥ 0
`currency`	`string`	required for loss_reported pattern `^[A-Z]{3}$`

Responses

Status	Body	Meaning
`201`	`Attestation`	Recorded
`400`	`Error`	Unknown type or field, missing required field, bad correction_of
`401`	`Error`	Not an RP key
`403`	`Error`	org:read key, or an RP key naming another subject
`404`	`Error`	Not this RP's decision

GET `/decisions/export`#

rpKey or orgKey or adminToken

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)

Parameters

Name	In	Type	Description
`since`	query	`string (date-time)`	evaluated_at ≥ since
`until`	query	`string (date-time)`	evaluated_at < until
`decision`	query	`"ALLOW"` \| `"DENY"`
`reason`	query	`ReasonCode`
`principal`	query	`DidWeb`
`grant_id`	query	`GrantId`
`cursor`	query	`string`	next_cursor from the previous page
`rp`	query	`DidWeb`	org keys: one member relying party (default: all of them); admin: any
`key_id`	query	`ApiKeyId`	only verifies made with this relying-party API key
`format`	query	`"ndjson"` \| `"csv"`
`limit`	query	`integer`

Responses

Status	Body	Meaning
`200`	`application/x-ndjson`	Rows, newest first. Headers X-Delegus-Rows and X-Delegus-Next-Cursor (empty on the last page).
`400`	`Error`	Bad filter or format
`401`	`Error`	No RP key, org key or admin token

GET `/decisions/stats`#

rpKey or orgKey or adminToken or observerKey

Decisions and outcomes rolled up per Principal over a range (default: last 30 days)

Parameters

Name	In	Type	Description
`since`	query	`string (date-time)`	inclusive; default 29 days ago 00:00Z
`until`	query	`string (date-time)`	exclusive; default tomorrow 00:00Z
`rp`	query	`DidWeb`	org keys: one member relying party; admin: any
`principal`	query	`DidWeb`	one Principal

Responses

Status	Body	Meaning
`200`	`DecisionStats`	OK
`400`	`Error`	Bad range
`401`	`Error`	No RP key, org key or admin token

Public#

Unauthenticated: evidence by hash (§8), status lists (§7), DID documents.

GET `/healthz`#

No auth

Liveness of every backing service the spec fails closed on

Responses

Status	Body	Meaning
`200`	`Health`	All backing services reachable
`503`	`Health`	A backing service is unreachable

GET `/evidence/{hash}`#

No auth

Exact bytes of an artifact by hash (§8)

Parameters

Name	In	Type	Description
`hash` required	path	`string`	sha256:<hex> or bare hex

Responses

Status	Body	Meaning
`200`	`/`	The bytes, with their original content type and immutable cache headers
`404`	`Error`	Unknown hash

GET `/status-lists/{path}`#

No auth

A Bitstring Status List credential (also served at the bare path on status.<domain>)

Parameters

Name	In	Type	Description
`path` required	path	`string`	<principal domain>/<list number>

Responses

Status	Body	Meaning
`200`	`application/vc+jwt`	Compact JWS (vc+jwt), Cache-Control max-age=30
`404`	`Error`	Unknown list

GET `/.well-known/did.json`#

No auth

The service DID document (receipt and status-list keys)

Responses

Status	Body	Meaning
`200`	`DidDocument`	OK

GET `/org/{slug}/did.json`#

No auth

A managed Principal's DID document

Parameters

Name	In	Type	Description
`slug` required	path	`string`

Responses

Status	Body	Meaning
`200`	`DidDocument`	application/did+json
`404`	`Error`	Unknown slug

Onboarding#

Registry administration.

POST `/principals`#

adminToken or orgKey

Register a managed or customer-hosted Principal

An org:admin key onboards into its own org; admin may pass org_id.

Request body · `PrincipalCreateRequest`

Responses

Status	Body	Meaning
`201`	`PrincipalCreated`	Registered; API key shown once
`400`	`Error`	Bad request
`401`	`Error`	Bad admin token
`409`	`Error`	Already registered, or a Delegus-managed domain

POST `/relying-parties`#

adminToken or orgKey

Register a relying party; returns its API key once

An org:admin key onboards into its own org; admin may pass org_id.

Request body · `RelyingPartyCreateRequest`

Field	Type	Description
`kind` required	`"managed"` \| `"hosted"`
`slug`	`string`
`did`	`string`	pattern `^did:web:`
`name`	`string`
`proof_window_seconds`	`integer`	≥ 1 · ≤ 300 · default `60`
`verify_rate_limit_per_minute`	`integer`	/verify requests per minute per API key (per node) ≥ 1 · ≤ 1000000 · default `600`
`org_id`	`OrgId`	admin: attach to this org; org:admin keys always onboard into their own org
`profile`	`"delegus-base-v1"` \| `"delegus-base-v2"`	default delegus-base-v1

Responses

Status	Body	Meaning
`201`	`RelyingPartyCreated`	Registered
`400`	`Error`	Bad request
`401`	`Error`	Bad admin token
`409`	`Error`	Already registered

GET `/relying-parties/{did}`#

rpKey or orgKey or adminToken

Relying-party settings

Parameters

Name	In	Type	Description
`did` required	path	`string`

Responses

Status	Body	Meaning
`200`	`RelyingParty`	OK
`401`	`Error`	Unauthorized
`404`	`Error`	Unknown relying party

PATCH `/relying-parties/{did}`#

adminToken or orgKey

Update a relying party's name, Proof window or /verify rate limit

Parameters

Name	In	Type	Description
`did` required	path	`DidWeb`

Request body · `RelyingPartyUpdateRequest`

Field	Type	Description
`name`	`string`	min length 1
`proof_window_seconds`	`integer`	≥ 1 · ≤ 300
`verify_rate_limit_per_minute`	`integer`	≥ 1 · ≤ 1000000
`profile`	`"delegus-base-v1"` \| `"delegus-base-v2"`	default delegus-base-v1

Responses

Status	Body	Meaning
`200`	`RelyingParty`	Updated
`400`	`Error`	Bad field
`401`	`Error`	Bad admin token
`404`	`Error`	Unknown relying party

POST `/orgs/self-serve`#

provisionKey

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.

Request body · `SelfServeRequest`

Field	Type	Description
`slug` required	`string`	Lowercase DNS label; becomes the org slug and the managed relying party did:web:<domain>:rp:<slug>. Taken or reserved slugs are 409. pattern `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$`
`name` required	`string`	min length 1 · max length 200
`admin_email` required	`string (email)`	max length 200

Responses

Status	Body	Meaning
`201`	`SelfServeBundle`	Provisioned
`400`	`Error`	Bad slug, name or admin_email
`401`	`Error`	Missing or wrong provision key
`404`	`Error`	Self-serve is not enabled on this deployment, or the relying party does not exist
`409`	`Error`	Slug taken or reserved
`429`	`Error`	Rate limited (per provision key, per customer IP, per relying party, or the daily ceiling)

POST `/orgs/self-serve/starter`#

provisionKey

Mint a fresh starter Grant and Proof for a self-serve relying party

Request body · `SelfServeRpRequest`

Field	Type	Description
`rp_did` required	`string`	A managed relying party created by POST /orgs/self-serve.

Responses

Status	Body	Meaning
`200`	`object`	A fresh starter
`400`	`Error`	rp_did is not a managed relying party DID
`401`	`Error`	Missing or wrong provision key
`404`	`Error`	Self-serve is not enabled on this deployment, or the relying party does not exist
`429`	`Error`	Rate limited (per provision key, per customer IP, per relying party, or the daily ceiling)

POST `/orgs/self-serve/first-receipt`#

provisionKey

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.

Request body · `SelfServeRpRequest`

Field	Type	Description
`rp_did` required	`string`	A managed relying party created by POST /orgs/self-serve.

Responses

Status	Body	Meaning
`200`	`Receipt`	The signed receipt (ALLOW for a healthy tenant)
`400`	`Error`	rp_did is not a managed relying party DID
`401`	`Error`	Missing or wrong provision key
`404`	`Error`	Self-serve is not enabled on this deployment, or the relying party does not exist
`429`	`Error`	Rate limited (per provision key, per customer IP, per relying party, or the daily ceiling)

Sandbox#

Present only when DELEGUS_DEMO=1 (development). Real receipts against an ephemeral sandbox Principal, Agent and relying party.

GET `/demo/info`#

No auth

Sandbox identities, the fixed Grant limits and lifetime

Responses

Status	Body	Meaning
`200`	`DemoInfo`	OK
`404`	`Error`	Sandbox disabled

POST `/demo/mint`#

No auth

Mint a sandbox Grant and a fresh Proof for a fixed purchase

Request body · `DemoMintRequest`

Field	Type	Description
`amount`	`integer`	minor units; the sandbox Grant allows up to 50000 USD ≥ 0 · ≤ 1000000000 · default `42700`

Responses

Status	Body	Meaning
`200`	`DemoMint`	OK
`404`	`Error`	Sandbox disabled
`429`	`Error`	Rate limited

POST `/demo/verify`#

No auth

POST /verify as the sandbox relying party (no key in the browser)

Request body · `VerifyRequest`

Field	Type	Description
`grant` required	`string`	Grant compact JWS as received in Delegus-Grant.
`proof` required	`string`	Proof compact JWS as received in Delegus-Proof.
`action` required	`Action`

Responses

Status	Body	Meaning
`200`	`Receipt`	OK
`400`	`Error`	Malformed envelope
`404`	`Error`	Sandbox disabled
`429`	`Error`	Rate limited

POST `/demo/revoke`#

No auth

Revoke a sandbox Grant

Request body · `RevokeRequest`

Field	Type	Description
`grant_id` required	`string`	pattern `^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$`

Responses

Status	Body	Meaning
`200`	`RevokeResponse`	OK
`400`	`Error`	Bad grant_id
`404`	`Error`	Sandbox disabled, or not a sandbox Grant
`429`	`Error`	Rate limited

Api-keys#

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.

GET `/me`#

principalKey or rpKey or orgKey

What the caller's API key resolves to (subject, role, settings); the check behind delegus doctor

Responses

Status	Body	Meaning
`200`	`Me`	OK
`401`	`Error`	Unknown or revoked key

GET `/api-keys`#

principalKey or rpKey or adminToken or orgKey

List the subject's API keys (ids only, never the keys)

Parameters

Name	In	Type	Description
`subject`	query	`DidWeb`	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).

Responses

Status	Body	Meaning
`200`	`ApiKeyList`	OK
`401`	`Error`	No live key and no admin token
`404`	`Error`	Admin named an unknown subject

POST `/api-keys`#

principalKey or rpKey or adminToken or orgKey

Issue an additional API key for the subject (rotation step 1)

Parameters

Name	In	Type	Description
`subject`	query	`DidWeb`	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).

Request body · `ApiKeyRequest`

Field	Type	Description
`label`	`string`	max length 100

Responses

Status	Body	Meaning
`201`	`ApiKeyIssued`	Issued; the key is shown once
`400`	`Error`	Bad label
`401`	`Error`	No live key and no admin token
`404`	`Error`	Admin named an unknown subject

POST `/api-keys/{key_id}/revoke`#

principalKey or rpKey or adminToken or orgKey

Revoke one of the subject's keys by id (rotation step 2, or a leaked key)

Parameters

Name	In	Type	Description
`key_id` required	path	`string`
`subject`	query	`DidWeb`	Admin only: act on this Principal or relying party instead of the caller's own subject.

Responses

Status	Body	Meaning
`200`	`ApiKey`	Revoked (idempotent)
`401`	`Error`	No live key and no admin token
`404`	`Error`	Not one of this subject's keys

Audit#

Append-only audit of administrative and Principal actions. Verify decisions are receipts, not audit events.

GET `/audit`#

adminToken or principalKey or rpKey or orgKey

Audit events, newest first: everything for admin; own actions for a Principal or relying party key; the org and its members for an org key

Parameters

Name	In	Type	Description
`actor`	query	`string`	admin only: filter by actor DID or org id
`action`	query	`string`	noun.verb
`target`	query	`string`
`since`	query	`string (date-time)`
`until`	query	`string (date-time)`
`limit`	query	`integer`
`cursor`	query	`string`	next_cursor from the previous page

Responses

Status	Body	Meaning
`200`	`AuditList`	OK
`400`	`Error`	Bad filter
`401`	`Error`	No key and no admin token

Usage#

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.

GET `/usage`#

rpKey or principalKey or adminToken or orgKey or observerKey

Verifies per UTC day over a range (default: the last 30 days)

Parameters

Name	In	Type	Description
`since`	query	`string (date-time)`	inclusive; default 29 days ago at 00:00Z
`until`	query	`string (date-time)`	exclusive; default tomorrow 00:00Z; range ≤ 366 days
`rp`	query	`DidWeb`	admin: any; org keys: one member relying party (default: all of them)
`principal`	query	`DidWeb`	admin: any; org keys: one member Principal
`key_id`	query	`ApiKeyId`	only verifies made with this relying-party API key
`by`	query	`"key"`	by=key adds a per-key breakdown to each day

Responses

Status	Body	Meaning
`200`	`Usage`	OK
`400`	`Error`	Bad range
`401`	`Error`	No key and no admin token

Orgs#

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.

POST `/orgs`#

adminToken

Create an organization (admin)

Request body · `OrgCreateRequest`

Field	Type	Description
`slug` required	`string`	lowercase DNS label, unique
`name` required	`string`	max length 200

Responses

Status	Body	Meaning
`201`	`Org`	Created
`400`	`Error`	Bad slug or name
`401`	`Error`	Not admin
`409`	`Error`	Slug taken

GET `/orgs/{org_id}`#

orgKey or adminToken

The org and its members

Parameters

Name	In	Type	Description
`org_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`OrgWithMembers`	OK
`401`	`Error`	Unauthorized
`404`	`Error`	Unknown org, or a key of another subject

POST `/orgs/{org_id}/members`#

adminToken

Attach an existing Principal or relying party to the org (admin)

Parameters

Name	In	Type	Description
`org_id` required	path	`string`

Request body · `OrgMemberRequest`

Field	Type	Description
`did` required	`DidWeb`	An existing Principal or relying party not yet in another org

Responses

Status	Body	Meaning
`200`	`OrgMemberAdded`	Attached (idempotent)
`400`	`Error`	Bad DID
`401`	`Error`	Not admin
`404`	`Error`	Unknown org or subject
`409`	`Error`	Subject belongs to another org

GET `/orgs/{org_id}/api-keys`#

orgKey or adminToken

The org's API keys (ids only)

Parameters

Name	In	Type	Description
`org_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`OrgApiKeyList`	OK
`401`	`Error`	Unauthorized
`404`	`Error`	Unknown org

POST `/orgs/{org_id}/api-keys`#

orgKey or adminToken

Issue an org key with role read or admin (shown once)

Parameters

Name	In	Type	Description
`org_id` required	path	`string`

Request body · `OrgApiKeyRequest`

Field	Type	Description
`role` required	`"read"` \| `"admin"`	read: every GET about the org and its members; admin: also onboarding, keys, revocation, agents, Principal keys, RP settings
`label`	`string`	max length 100

Responses

Status	Body	Meaning
`201`	`ApiKeyIssued`	Issued
`400`	`Error`	Bad role or label
`401`	`Error`	Unauthorized
`403`	`Error`	org:read key cannot issue keys
`404`	`Error`	Unknown org

POST `/orgs/{org_id}/api-keys/{key_id}/revoke`#

orgKey or adminToken

Revoke an org key by its public id (immediate, idempotent)

Parameters

Name	In	Type	Description
`org_id` required	path	`string`
`key_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`ApiKey`	Revoked
`401`	`Error`	Unauthorized
`403`	`Error`	org:read key cannot revoke keys
`404`	`Error`	Unknown org or key

GET `/orgs/{org_id}/entitlement`#

provisionKey or adminToken

Read an org's production entitlement and what the gate would decide now (console, admin)

Parameters

Name	In	Type	Description
`org_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`Entitlement`	The stored row (null fields when none is stored) and the effective decision
`401`	`Error`	Not the provision key or admin
`404`	`Error`	Unknown org

PUT `/orgs/{org_id}/entitlement`#

provisionKey or adminToken

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.

Parameters

Name	In	Type	Description
`org_id` required	path	`string`

Request body · `EntitlementRequest`

Field	Type	Description
`production` required	`"allowed"` \| `"blocked"`
`production_until` required	`string \| null (date-time)`	Production checks stop at this instant; null for no end.
`check_cap` required	`integer \| null`	At most this many production checks since cap_since; null for no cap. ≥ 0 · ≤ 1000000000
`cap_since` required	`string \| null (date-time)`	Start of the capped count; required with check_cap. A new value starts a fresh count.
`reason` required	`"trial"` \| `"paid"` \| `"past_due_grace"` \| `"canceled"` \| `"comp"` \| `"none"`
`as_of` required	`string (date-time)`	The console's change time. At most five minutes ahead of the server clock.

Responses

Status	Body	Meaning
`200`	`Entitlement`	Stored (applied true) or ignored as older than the stored row (applied false); the row now in effect
`400`	`Error`	Invalid body
`401`	`Error`	Not the provision key or admin
`404`	`Error`	Unknown org

Transparency#

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/… .

GET `/checkpoints/latest`#

No auth

The most recent closed day's checkpoint

Responses

Status	Body	Meaning
`200`	`Checkpoint`	OK
`404`	`Error`	No day closed yet

GET `/checkpoints/{day}`#

No auth

The checkpoint for a UTC day (immutable once published)

Parameters

Name	In	Type	Description
`day` required	path	`string`	UTC day

Responses

Status	Body	Meaning
`200`	`Checkpoint`	OK
`404`	`Error`	Day not closed, or not a UTC day

GET `/checkpoints/{day}/leaves`#

No auth

The day's leaf hashes, one hex SHA-256 per line in tree order; merkleRoot(leaves) equals the checkpoint root

Parameters

Name	In	Type	Description
`day` required	path	`string`	UTC day

Responses

Status	Body	Meaning
`200`	`text/plain`	text/plain; headers X-Delegus-Tree-Size and X-Delegus-Root
`404`	`Error`	Day not closed

POST `/checkpoints/close`#

adminToken

Close every ended UTC day now (admin; idempotent; the maintenance loop does this every 5 minutes)

Responses

Status	Body	Meaning
`200`	`CheckpointsClosed`	Days closed in this run
`401`	`Error`	Not admin

GET `/decisions/{receipt_id}/inclusion`#

No auth

Inclusion proof of a receipt id in its day's checkpoint; 202 while the day is still open

Parameters

Name	In	Type	Description
`receipt_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`InclusionProof`	Proof
`202`	`InclusionPending`	Day not closed yet (Retry-After: 3600)
`404`	`Error`	Unknown receipt

Authzen#

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.

POST `/access/v1/evaluation`#

rpKey

AuthZEN Access Evaluation: subject/action/resource/context → decision, backed by a Delegus receipt

Request body · `AuthZenRequest`

Field Type Description

subject required AuthZenEntity type "agent", id = the Agent's did:key; properties.grant and properties.proof = the compact JWS the Agent presented (context.grant/proof also accepted)

action required

object

Field	Type	Description
`name` required	`"commerce:purchase"` \| `"api:call"`
`properties`	`object`	the remaining Delegus Action fields: amount, currency (commerce:purchase) or method (api:call); never type or resource

resource required AuthZenEntity id = the Delegus action.resource (order id or absolute URL)

context object

Responses

Status	Body	Meaning
`200`	`AuthZenResponse`	Decision (true only for ALLOW); context carries the Delegus reason and the receipt
`400`	`Error`	Request does not map to a verification (no permit)
`401`	`Error`	Not a relying-party key
`402`	`Error`	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.
`429`	`Error`	Rate limited (the RP's verify limit)

GET `/.well-known/authzen-configuration`#

No auth

AuthZEN PDP metadata

Responses

Status	Body	Meaning
`200`	`AuthZenConfiguration`	OK

Metrics#

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.

GET `/metrics`#

No auth

Aggregate service metrics (public, no per-subject data)

Parameters

Name	In	Type	Description
`days`	query	`integer`	verify-total window

Responses

Status	Body	Meaning
`200`	`Metrics`	OK
`400`	`Error`	Bad days

GET `/observer-keys`#

adminToken

List observer keys (admin)

Responses

Status	Body	Meaning
`200`	`ApiKeyList`	OK
`401`	`Error`	Not admin

POST `/observer-keys`#

adminToken

Issue an observer key: service-wide read of /decisions/stats and /usage only (admin; shown once)

Request body · `ApiKeyRequest`

Field	Type	Description
`label`	`string`	max length 100

Responses

Status	Body	Meaning
`201`	`ApiKeyIssued`	Issued
`401`	`Error`	Not admin

POST `/observer-keys/{key_id}/revoke`#

adminToken

Revoke an observer key (admin)

Parameters

Name	In	Type	Description
`key_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`ApiKey`	Revoked
`401`	`Error`	Not admin
`404`	`Error`	Unknown observer key

Conformance#

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.

POST `/conformance/runs`#

rpKey or principalKey or orgKey or adminToken

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 50 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}.

Request body · `ConformanceRunRequest`

Field	Type	Description
`endpoint` required	`string (uri)`	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. max length 2048

Responses

Status	Body	Meaning
`202`	`ConformanceRun`	Started
`400`	`Error`	Not an https URL, carries credentials, or is a Delegus host
`401`	`Error`	No valid key
`409`	`Error`	A run is already running for this account
`429`	`Error`	Rate limited

GET `/conformance/runs/{run_id}`#

rpKey or principalKey or orgKey or adminToken

Read a hosted conformance run and its report

Parameters

Name	In	Type	Description
`run_id` required	path	`string`

Responses

Status	Body	Meaning
`200`	`ConformanceRun`	The run
`401`	`Error`	No valid key
`404`	`Error`	No such run for this account

Schemas#

Every object the API accepts or returns. ReasonCode values link to their definition on the DENY reason codes page.

`Action`oneOf#

The RP's description of the action (§3.3, §5.1). Integers only, no floats.

One of: object | object

`Agent`object#

Field	Type	Description
`did` required	`string`	pattern `^did:key:z6Mk`
`principal` required	`string`	pattern `^did:web:`
`created_at` required	`string (date-time)`	RFC 3339 UTC

`AgentDisabled`object#

Field	Type	Description
`did` required	`string`	pattern `^did:key:z6Mk`
`disabled_at` required	`string (date-time)`	RFC 3339 UTC
`revoked_grants` required	`string[]`

`AgentRequest`object#

Field	Type	Description
`did` required	`string`	pattern `^did:key:z6Mk`

`ApiKey`object#

Field	Type	Description
`key_id` required	`string`	Public identifier (first 12 hex chars of the key hash); never a secret.
`role` required	`"principal"` \| `"rp"` \| `"org:read"` \| `"org:admin"` \| `"observer"`
`subject` required	`string`	The Principal or relying-party DID, or the org id for org keys
`label` required	`string \| null`
`created_at` required	`string (date-time)`
`revoked_at` required	`string (date-time)` \| `null`

`ApiKeyId`string#

Public identifier of an API key (first 12 hex chars of its hash); never a secret.

string · pattern ^[0-9a-f]{12}$

`ApiKeyIssued`object#

ApiKey & object

`ApiKeyList`object#

Field	Type	Description
`subject` required	`DidWeb`
`keys` required	`ApiKey[]`

`ApiKeyRequest`object#

Field	Type	Description
`label`	`string`	max length 100

`Attestation`object#

OutcomeEvent & object

`AuditEvent`object#

Field Type Description

event_id required

string

pattern ^aud_

occurred_at required string (date-time)

actor required

object

Field	Type	Description
`kind` required	`"admin"` \| `"principal"` \| `"rp"` \| `"org"` \| `"system"`
`did` required	`string \| null`	The subject DID, or the org id for org keys
`key_id` required	`string \| null`

action required string principal.create, principal.verify, relying_party.create, api_key.create, api_key.revoke, agent.register, agent.disable, grant.allocate, grant.revoke, key.compromise, sandbox.create, key.retire, relying_party.update

target required string | null

request_id required string | null

details required object

`AuditList`object#

Field	Type	Description
`events` required	`AuditEvent[]`
`next_cursor` required	`string \| null`

`AuthZenConfiguration`object#

Field	Type	Description
`policy_decision_point` required	`string (uri)`
`access_evaluation_endpoint` required	`string (uri)`
`delegus`	`object`

`AuthZenEntity`object#

Field	Type	Description
`type` required	`string`
`id` required	`string`
`properties`	`object`

`AuthZenRequest`object#

Field Type Description

subject required AuthZenEntity type "agent", id = the Agent's did:key; properties.grant and properties.proof = the compact JWS the Agent presented (context.grant/proof also accepted)

action required

object

Field	Type	Description
`name` required	`"commerce:purchase"` \| `"api:call"`
`properties`	`object`	the remaining Delegus Action fields: amount, currency (commerce:purchase) or method (api:call); never type or resource

resource required AuthZenEntity id = the Delegus action.resource (order id or absolute URL)

context object

`AuthZenResponse`object#

Field Type Description

decision required boolean true iff the Delegus receipt says ALLOW

context required

object

Field	Type	Description
`reason` required	`ReasonCode` \| `null`
`receipt_id` required	`string`
`evaluated_at` required	`string (date-time)`
`relying_party` required	`DidWeb`
`principal`	`DidWeb`
`agent`	`DidKey`
`receipt` required	`string`	the signed receipt JWS
`receipt_url` required	`string`
`issuer` required	`DidWeb`

`Capability`object#

Field	Type	Description
`action` required	`"commerce:purchase"` \| `"api:call"`
`constraints` required	`object`	commerce:purchase: maxAmount (integer, minor units), currency (ISO 4217). api:call: methods (uppercase HTTP methods). Unknown keys deny at P17.
`resources`	`string[]`	Globs with * and ** only; absent = ["*"].

`CheckOutcome`oneOf#

Check outcome: true, false, or "skipped" when a prerequisite did not pass.

One of: boolean | "skipped"

`Checkpoint`object#

Field	Type	Description
`day` required	`string`	pattern `^\d{4}-\d{2}-\d{2}$`
`tree_size` required	`integer`	≥ 0
`root` required	`Sha256`
`previous_root` required	`Sha256` \| `null`	The previous day's root; null for the first checkpoint
`first_receipt_id` required	`string \| null`
`last_receipt_id` required	`string \| null`
`tree` required	`"rfc6962-sha256"`
`kid` required	`string`	did:web:<domain>#status-<n>, the signing key
`checkpoint` required	`string`	Compact JWS, typ delegus-checkpoint+jwt, JCS payload {iss, day, tree_size, root, previous_root, first_receipt_id, last_receipt_id, iat, tree}
`checkpoint_hash` required	`Sha256`
`leaves_url` required	`string`
`created_at` required	`string (date-time)`

`CheckpointsClosed`object#

Field	Type	Description
`closed` required	`string[]`
`latest` required	`string \| null`

`ConformanceRun`object#

Field Type Description

run_id required string cfr_<ULID>

status required "running" | "passed" | "failed" | "error" 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.

endpoint required string

created_at required string (date-time)

finished_at required string (date-time) | null

requests required integer Requests sent to the endpoint (at most 50 per run).

vectors required

object

Field	Type	Description
`sha256` required	`string`	sha256 over the vector set that ran (recompute with vectorSetHash()).
`conformance_version` required	`string`

error required string | null

report required object | null

signed required false Reports are unsigned in v1.

`ConformanceRunRequest`object#

Field	Type	Description
`endpoint` required	`string (uri)`	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. max length 2048

`ConsumptionBalance`object#

Field Type Description

key required Sha256 sha256 over the RFC 8785 form of the Capability (v0.3 proposal §3)

spent_total required integer

spent_in_period required integer

period_start required string (date-time) | null

uses_spent required integer

limits required

object

as seen at the last consume

Field	Type	Description
`total`	`integer \| null`
`per_period`	`integer \| null`
`uses`	`integer \| null`

remaining required

object

Field	Type	Description
`total`	`integer \| null`
`per_period`	`integer \| null`
`uses`	`integer \| null`

updated_at required string (date-time)

`ConsumptionEvent`object#

Field	Type	Description
`version` required	`integer`
`key` required	`Sha256`
`delta_total` required	`integer`
`delta_period` required	`integer`
`delta_uses` required	`integer`
`period_start` required	`string (date-time)` \| `null`
`cause` required	`"consume"` \| `"restore"` \| `"restore_reversal"`
`cause_id` required	`string`	receipt id (consume) or attestation id (restore, restore_reversal)
`receipt_id` required	`string`
`recorded_at` required	`string (date-time)`

`CredentialStatus`object#

Field	Type	Description
`id` required	`string`
`type` required	`"BitstringStatusListEntry"`
`statusPurpose` required	`"revocation"`
`statusListIndex` required	`string`	pattern `^(0\|[1-9][0-9]*)$`
`statusListCredential` required	`string (uri)`

`Decision`object#

Field	Type	Description
`receipt` required	`Receipt`
`outcomes` required	`Attestation[]`

`DecisionExportRow`object#

One NDJSON line: the decision summary, the full signed receipt, and its outcome ledger

DecisionSummary & object

`DecisionList`object#

Field	Type	Description
`decisions` required	`DecisionSummary[]`
`next_cursor` required	`string \| null`	Pass as ?cursor= for the next (older) page; null when this was the last page.

`DecisionStats`object#

Field Type Description

since required string (date-time)

until required string (date-time)

rps DidWeb[]

totals required

object

Field	Type	Description
`verifies` required	`integer`
`allow` required	`integer`
`deny` required	`integer`
`allow_with_outcome` required	`integer`

principals required PrincipalStats[]

`DecisionSummary`object#

Field	Type	Description
`receipt_id` required	`string`
`decision` required	`"ALLOW"` \| `"DENY"`
`reason` required	`ReasonCode` \| `null`
`evaluated_at` required	`string (date-time)`
`principal` required	`DidWeb` \| `null`
`grant_id` required	`GrantId` \| `null`
`agent` required	`DidKey` \| `null`
`rp` required	`DidWeb`
`key_id` required	`ApiKeyId` \| `null`	The relying-party key that made the verify; null before key tracking
`action_type` required	`"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).
`amount` required	`integer` \| `null`	commerce:purchase: integer minor units of `currency` (JPY has 0 decimals, USD 2, KWD 3). Null otherwise.
`currency` required	`string` \| `null`	commerce:purchase: ISO 4217 code. Null otherwise.
`resource` required	`string` \| `null`	The action resource as submitted (a purchase resource or an api:call URI).
`method` required	`string` \| `null`	api:call: the HTTP method. Null otherwise.

`DemoInfo`object#

Field Type Description

principal required DidWeb

agent required DidKey

rp required DidWeb

authority required Capability

grant_lifetime_seconds required integer

request required

object

Field	Type	Description
`method`	`string`
`url`	`string`

amount_cap required integer

rate_limit_per_minute required integer

`DemoMint`object#

Field Type Description

grant required string

proof required string

action required Action

rp required

string

pattern ^did:web:

grant_id required

string

pattern ^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$

agent required

string

pattern ^did:key:z6Mk

principal required

string

pattern ^did:web:

request required

object

Field	Type	Description
`method`	`string`
`url`	`string`

authority required Capability

valid_until required string (date-time)

grant_lifetime_seconds required integer

`DemoMintRequest`object#

Field	Type	Description
`amount`	`integer`	minor units; the sandbox Grant allows up to 50000 USD ≥ 0 · ≤ 1000000000 · default `42700`

`DidDocument`object#

Field Type Description

@context required string[]

id required

string

pattern ^did:web:

verificationMethod required

object[]

Field	Type	Description
`id` required	`string`
`type` required	`"Multikey"`
`controller` required	`string`	pattern `^did:web:`
`publicKeyMultibase` required	`string`

assertionMethod string[]

`DidKey`string#

string · pattern ^did:key:z6Mk

`DidWeb`string#

string · pattern ^did:web:

`Entitlement`object#

Field	Type	Description
`org_id` required	`string`
`stored` required	`boolean`	Whether a row exists. With enforcement on, no row means no plan.
`production`	`"allowed"` \| `"blocked"` \| `null`
`production_until`	`string \| null (date-time)`
`check_cap`	`integer \| null`
`cap_since`	`string \| null (date-time)`
`reason`	`enum (7)`	one of: `trial`, `paid`, `past_due_grace`, `canceled`, `comp`, `none`, `null`
`as_of`	`string \| null (date-time)`
`updated_at`	`string \| null (date-time)`
`production_checks_since_cap`	`integer \| null`	Production checks counted since cap_since (at most check_cap); null without a cap.
`comp` required	`boolean`	A staff, self-test or canary tenant that never needs a plan.
`effective` required	`"allowed"` \| `"blocked"`	What the gate would decide for the next production check now.
`effective_detail`	`string \| null`	Why it would be refused; null when allowed.
`enforced` required	`boolean`	Whether this deployment refuses (true) or only logs (false) a blocked production check.
`applied`	`boolean`	PUT only: whether this push was stored.

`EntitlementRequest`object#

Field	Type	Description
`production` required	`"allowed"` \| `"blocked"`
`production_until` required	`string \| null (date-time)`	Production checks stop at this instant; null for no end.
`check_cap` required	`integer \| null`	At most this many production checks since cap_since; null for no cap. ≥ 0 · ≤ 1000000000
`cap_since` required	`string \| null (date-time)`	Start of the capped count; required with check_cap. A new value starts a fresh count.
`reason` required	`"trial"` \| `"paid"` \| `"past_due_grace"` \| `"canceled"` \| `"comp"` \| `"none"`
`as_of` required	`string (date-time)`	The console's change time. At most five minutes ahead of the server clock.

`Error`object#

Field	Type	Description
`error` required	`enum (10)`	one of: `INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `PAYLOAD_TOO_LARGE`, `SERVICE_UNAVAILABLE`, `METHOD_NOT_ALLOWED`, `INTERNAL`, `RATE_LIMITED`
`message` required	`string`

`GrantAllocation`object#

The Principal signs these into the Grant (§3.2 rows 6 and 14).

Field	Type	Description
`id` required	`string`	pattern `^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$`
`issuer` required	`string`	pattern `^did:web:`
`agent` required	`string`	pattern `^did:key:z6Mk`
`credentialStatus` required	`CredentialStatus`
`allocated_at` required	`string (date-time)`	RFC 3339 UTC

`GrantAllocationRequest`object#

Field	Type	Description
`agent` required	`string`	pattern `^did:key:z6Mk`

`GrantConsumption`object#

Balances and the append-only consumption log of one Grant (v0.3 consumable Grants, proposal §7–§8). Empty for Grants that were never consumed.

Field	Type	Description
`grant_id` required	`GrantId`
`principal` required	`DidWeb`
`agent` required	`DidKey`
`version` required	`integer`	log version; 0 when never consumed
`as_of` required	`string (date-time)`
`snapshot_hash` required	`Sha256`	hash of the canonical consumption snapshot as of now (what a v0.3 receipt would pin)
`capabilities` required	`ConsumptionBalance[]`
`events` required	`ConsumptionEvent[]`	newest first
`next_cursor` required	`integer \| null`

`GrantId`string#

string · pattern ^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$

`GrantList`object#

Field	Type	Description
`grants` required	`GrantSummary[]`
`next_cursor` required	`string \| null`

`GrantSummary`object#

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.

Field	Type	Description
`id` required	`GrantId`
`principal` required	`DidWeb`
`agent` required	`DidKey`
`status_list` required	`string (uri)`
`status_list_index` required	`integer`
`allocated_at` required	`string (date-time)`
`revoked_at` required	`string (date-time)` \| `null`
`state` required	`"active"` \| `"revoked"`

`Health`object#

Field	Type	Description
`ok` required	`boolean`
`env`	`string`
`did`	`string`	pattern `^did:web:`

`InclusionPending`object#

Field	Type	Description
`receipt_id` required	`string`
`day` required	`string`
`status` required	`string`

`InclusionProof`object#

Field	Type	Description
`receipt_id` required	`string`
`day` required	`string`
`leaf` required	`string`	hex SHA-256(0x00 ‖ receipt_id)
`leaf_index` required	`integer`	≥ 0
`tree_size` required	`integer`	≥ 1
`root` required	`Sha256`
`audit_path` required	`string[]`	RFC 6962 §2.1.1 audit path, hex, leaf to root
`checkpoint` required	`string`	The day's checkpoint JWS
`kid` required	`string`

`KeyCompromised`object#

Field	Type	Description
`kid` required	`string`
`state` required	`"compromised"`

`KeyRetired`object#

Field	Type	Description
`kid` required	`string`
`state` required	`"retired"` \| `"compromised"`

`Me`object#

Field Type Description

subject required string DID, or org id for org keys

role required "principal" | "rp" | "org:read" | "org:admin" | "observer"

key_id required string

key_label string | null

key_created_at string (date-time)

service_did required DidWeb

env required string

name string relying parties

proof_window_seconds integer relying parties

kind "managed" | "hosted" principals

verification Verification

keys

object[]

principals: signing keys known from the DID document and their trust state

Field	Type	Description
`kid`	`string`
`state`	`"active"` \| `"retired"` \| `"compromised"`

org_id OrgId | null Principals and relying parties: their org

org Org org keys

members OrgMember[] org keys

scope string[] observer keys: the endpoints the key may call

`Metrics`object#

Aggregate only; no Principal, relying-party or receipt identifiers appear.

Field Type Description

as_of required string (date-time)

service_did required DidWeb

env required string

principals required

object

Field	Type	Description
`verified` required	`integer`
`hosted_verified` required	`integer`
`hosted_unverified` required	`integer`
`managed` required	`integer`

relying_parties required integer

organizations required integer

receipts_total required integer

verifies required

object

Field Type Description

window_days required integer

since required string (date-time)

until required string (date-time)

verifies required integer

allow required integer

deny required integer

per_day required

object[]

Field	Type	Description
`day` required	`string`
`verifies` required	`integer`
`allow` required	`integer`
`deny` required	`integer`

transparency required

object

Field	Type	Description
`latest_day`	`string \| null`
`latest_root`	`Sha256`
`latest_tree_size`	`integer`
`checkpoints`	`integer`

named_principals required

object[]

verified Principals that opted in to public naming

Field	Type	Description
`did` required	`DidWeb`
`domain` required	`string`
`kind` required	`"managed"` \| `"hosted"`

self_test required

object

self-test/liveness tenants, excluded from the customer counters above; never a customer

Field	Type	Description
`principals` required	`integer`
`relying_parties` required	`integer`
`organizations` required	`integer`

`Org`object#

Field	Type	Description
`org_id` required	`OrgId`
`slug` required	`string`
`name` required	`string`
`created_at` required	`string (date-time)`

`OrgApiKeyList`object#

Field	Type	Description
`org_id` required	`OrgId`
`keys` required	`ApiKey[]`

`OrgApiKeyRequest`object#

Field	Type	Description
`role` required	`"read"` \| `"admin"`	read: every GET about the org and its members; admin: also onboarding, keys, revocation, agents, Principal keys, RP settings
`label`	`string`	max length 100

`OrgCreateRequest`object#

Field	Type	Description
`slug` required	`string`	lowercase DNS label, unique
`name` required	`string`	max length 200

`OrgId`string#

string · pattern ^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$

`OrgMember`object#

Field	Type	Description
`did` required	`DidWeb`
`kind` required	`"principal"` \| `"relying_party"`
`created_at` required	`string (date-time)`
`principal_kind`	`"managed"` \| `"hosted"`	principals
`domain`	`string`	principals
`verification_state`	`"verified"` \| `"unverified"`	principals
`verification`	`Verification`	principals
`name`	`string`	relying parties
`proof_window_seconds`	`integer`	relying parties
`verify_rate_limit_per_minute`	`integer`	relying parties

`OrgMemberAdded`object#

Field	Type	Description
`org_id` required	`OrgId`
`did` required	`DidWeb`
`kind` required	`"principal"` \| `"relying_party"`

`OrgMemberRequest`object#

Field	Type	Description
`did` required	`DidWeb`	An existing Principal or relying party not yet in another org

`OrgWithMembers`object#

Org & object

`OutcomeEvent`object#

Unknown fields and unknown types are rejected (§9.3).

Field	Type	Description
`type` required	`enum (7)`	one of: `fulfilled`, `cancelled`, `dispute_opened`, `dispute_resolved`, `chargeback_received`, `chargeback_reversed`, `loss_reported`
`occurred_at` required	`string (date-time)`	RFC 3339 UTC
`evidence_ref`	`string`
`note`	`string`
`correction_of`	`string`	pattern `^oat_`
`reporter_signature`	`string`
`resolution`	`"agent_at_fault"` \| `"agent_not_at_fault"` \| `"indeterminate"`	required for dispute_resolved
`loss_amount`	`integer`	required for loss_reported; minor units ≥ 0
`currency`	`string`	required for loss_reported pattern `^[A-Z]{3}$`

`Principal`object#

Field	Type	Description
`did` required	`string`	pattern `^did:web:`
`kind` required	`"managed"` \| `"hosted"`
`domain` required	`string`
`verification` required	`Verification`
`created_at` required	`string (date-time)`	RFC 3339 UTC
`org_id`	`OrgId` \| `null`
`may_be_named`	`boolean`	consent to be named publicly (metrics page); default false, admin-set

`PrincipalCreated`object#

Principal & object

`PrincipalCreateRequest`oneOf#

One of: object | object

`PrincipalDirectory`object#

Field	Type	Description
`principals` required	`PrincipalDirectoryEntry[]`
`next_cursor` required	`DidWeb` \| `null`

`PrincipalDirectoryEntry`object#

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.

Field Type Description

did required DidWeb

kind required "managed" | "hosted"

domain required string

verification required

object

Field	Type	Description
`state` required	`"verified"` \| `"unverified"`
`verified_since` required	`string (date-time)` \| `null`
`last_checked_at` required	`string (date-time)` \| `null`
`method` required	`"domain"` \| `"delegus-hosted"`	domain: DNS TXT or .well-known proof, re-checked every 24 h; delegus-hosted: managed Principal, verified by construction

keys required

object[]

Key history: every verification method ever seen, with its current state

Field	Type	Description
`kid` required	`string`
`state` required	`"active"` \| `"retired"` \| `"compromised"`
`since` required	`string (date-time)`

did_document required object | null

registered_at required string (date-time)

may_be_named boolean consent to be named publicly (metrics page); default false, admin-set

`PrincipalNamingRequest`object#

Field	Type	Description
`may_be_named` required	`boolean`

`PrincipalStats`object#

Field	Type	Description
`principal` required	`DidWeb` \| `null`	null groups receipts denied before the Grant was authenticated (P1–P3, T1–T3)
`verifies` required	`integer`
`allow` required	`integer`
`deny` required	`integer`
`reasons` required	`object`	DENY reason → count
`outcomes` required	`object`	outcome type → count
`losses` required	`object`	loss_reported sums per currency, minor units
`allow_with_outcome` required	`integer`	ALLOW receipts with at least one outcome attestation

`ProtocolCheckId`string#

P1 P2 P3 P4 P5 P6 P7 P8 P9 P10 P11 P12 P13 P14 P15 P16 P17 P18 P19 P20

`Receipt`object#

Decision Receipt (spec §6.2). receipt is the canonical non-detached compact JWS over JCS(body minus receipt).

Field Type Description

receipt_version required "delegus-receipt-v1"

receipt_id required

string

pattern ^drc_[0-7][0-9A-HJKMNP-TV-Z]{25}$

decision required "ALLOW" | "DENY"

reason required ReasonCode | null

evaluated_at required string (date-time) RFC 3339 UTC

relying_party required

string

pattern ^did:web:

principal

object

Present only once P3 passed (§6.4).

Field	Type	Description
`id` required	`string`	pattern `^did:web:`
`verification` required	`"domain"` \| `"unverified"`

agent

string

pattern ^did:key:z6Mk

grant_id

string

pattern ^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$

grant_hash required

string

The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).

pattern ^sha256:[0-9a-f]{64}$

proof_hash required

string

The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).

pattern ^sha256:[0-9a-f]{64}$

request_hash

string

The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).

pattern ^sha256:[0-9a-f]{64}$

authority Capability | null The Capability that authorized the action; null on DENY; absent before P3.

expires_at string (date-time) RFC 3339 UTC

evidence required

object

Field Type Description

issuer_resolution

object

Field	Type	Description
`did` required	`string`	pattern `^did:web:`
`did_document_hash` required	`string`	The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3). pattern `^sha256:[0-9a-f]{64}$`
`resolved_at` required	`string (date-time)`	RFC 3339 UTC

status

object

Field	Type	Description
`credential_url` required	`string (uri)`
`credential_hash` required	`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_at` required	`string (date-time)`	RFC 3339 UTC
`status_list_index` required	`string`

trust_config_version required string

trust_config_hash required

string

The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).

pattern ^sha256:[0-9a-f]{64}$

protocol required

object

Field Type Description

result required "PASS" | "FAIL"

profile required "delegus-base-v1"

profile_hash required

string

The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).

pattern ^sha256:[0-9a-f]{64}$

checks required

object

Field	Type	Description
`P1` required	`CheckOutcome`
`P2` required	`CheckOutcome`
`P3` required	`CheckOutcome`
`P4` required	`CheckOutcome`
`P5` required	`CheckOutcome`
`P6` required	`CheckOutcome`
`P7` required	`CheckOutcome`
`P8` required	`CheckOutcome`
`P9` required	`CheckOutcome`
`P10` required	`CheckOutcome`
`P11` required	`CheckOutcome`
`P12` required	`CheckOutcome`
`P13` required	`CheckOutcome`
`P14` required	`CheckOutcome`
`P15` required	`CheckOutcome`
`P16` required	`CheckOutcome`
`P17` required	`CheckOutcome`
`P18` required	`CheckOutcome`
`P19` required	`CheckOutcome`
`P20` required	`CheckOutcome`

trust required

object

Field Type Description

result required "PASS" | "FAIL"

policy_version required "delegus-trust-v1"

checks required

object

Field	Type	Description
`T1` required	`CheckOutcome`
`T2` required	`CheckOutcome`
`T3` required	`CheckOutcome`
`T5` required	`CheckOutcome`

receipt required string Compact JWS, alg EdDSA, typ delegus-receipt+jwt, kid did:web:<domain>#receipt-<n>.

`RelyingParty`object#

Field	Type	Description
`did` required	`DidWeb`
`name` required	`string`
`proof_window_seconds` required	`integer`
`verify_rate_limit_per_minute` required	`integer`
`created_at` required	`string (date-time)`
`org_id`	`OrgId` \| `null`
`profile`	`"delegus-base-v1"` \| `"delegus-base-v2"`	Protocol profile for /verify; v2 enables consumable grants (budget). Default v1.

`RelyingPartyCreated`object#

Field	Type	Description
`did` required	`string`	pattern `^did:web:`
`name` required	`string`
`proof_window_seconds` required	`integer`
`created_at` required	`string (date-time)`	RFC 3339 UTC
`api_key` required	`string`	Shown once.
`api_key_id` required	`string`
`verify_rate_limit_per_minute` required	`integer`

`RelyingPartyCreateRequest`object#

Field	Type	Description
`kind` required	`"managed"` \| `"hosted"`
`slug`	`string`
`did`	`string`	pattern `^did:web:`
`name`	`string`
`proof_window_seconds`	`integer`	≥ 1 · ≤ 300 · default `60`
`verify_rate_limit_per_minute`	`integer`	/verify requests per minute per API key (per node) ≥ 1 · ≤ 1000000 · default `600`
`org_id`	`OrgId`	admin: attach to this org; org:admin keys always onboard into their own org
`profile`	`"delegus-base-v1"` \| `"delegus-base-v2"`	default delegus-base-v1

`RelyingPartyUpdateRequest`object#

Field	Type	Description
`name`	`string`	min length 1
`proof_window_seconds`	`integer`	≥ 1 · ≤ 300
`verify_rate_limit_per_minute`	`integer`	≥ 1 · ≤ 1000000
`profile`	`"delegus-base-v1"` \| `"delegus-base-v2"`	default delegus-base-v1

`RevokeRequest`object#

Field	Type	Description
`grant_id` required	`string`	pattern `^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$`

`RevokeResponse`object#

Field	Type	Description
`grant_id` required	`string`	pattern `^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$`
`revoked` required	`true`
`revoked_at` required	`string (date-time)`	RFC 3339 UTC

`SelfServeBundle`object#

Field Type Description

org required Org

org_admin_key required string org:admin key for the new org (dk_org_admin_…). Shown once; the console keeps it server-side and never shows it to the customer.

relying_party required

object

The tenant's managed relying party. Managed identities are verified at creation; nothing is pending.

Field	Type	Description
`did` required	`string`
`name` required	`string`
`profile` required	`string`
`proof_window_seconds` required	`integer`

rp_verify_key required string The customer's first relying-party verify key (dk_rp_…). Shown once.

starter required SelfServeStarter

`SelfServeRequest`object#

Field	Type	Description
`slug` required	`string`	Lowercase DNS label; becomes the org slug and the managed relying party did:web:<domain>:rp:<slug>. Taken or reserved slugs are 409. pattern `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$`
`name` required	`string`	min length 1 · max length 200
`admin_email` required	`string (email)`	max length 200

`SelfServeRpRequest`object#

Field	Type	Description
`rp_did` required	`string`	A managed relying party created by POST /orgs/self-serve.

`SelfServeStarter`object#

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 ceiling, 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
`grant` required	`string`	Grant compact JWS (vc+jwt).
`proof` required	`string`	Proof compact JWS (delegus-proof+jwt), aud = this relying party.
`action` required	`object`	The exact Action the Proof is bound to (a $10.00 sandbox purchase).
`grant_id` required	`string`
`expires_at` required	`string (date-time)`	When the Proof leaves the relying party's 300-second window; call /orgs/self-serve/starter for a fresh one.
`verify_url` required	`string (uri)`
`verify_curl` required	`string`	A ready shell command for /verify; the literal <rp_verify_key> marks where the customer's key goes.

`Sha256`string#

The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec §6.3).

string · pattern ^sha256:[0-9a-f]{64}$

`TrustCheckId`string#

T1 T2 T3 T5

`Usage`object#

Field Type Description

since required string (date-time)

until required string (date-time)

rp DidWeb

principal DidWeb

totals required

object

Field	Type	Description
`verifies` required	`integer`
`allow` required	`integer`
`deny` required	`integer`

days required UsageDay[]

rps DidWeb[] org keys: the relying parties covered

key_id ApiKeyId

`UsageDay`object#

Field	Type	Description
`day` required	`string`	UTC day pattern `^\d{4}-\d{2}-\d{2}$`
`verifies` required	`integer`
`allow` required	`integer`
`deny` required	`integer`
`reasons` required	`object`	DENY reason → count
`keys`	`object`	Present with by=key: per API key id ("unknown" for receipts recorded before key tracking)

`Verification`object#

Field Type Description

state required "verified" | "unverified"

token required string

dns_txt required

object

Field	Type	Description
`name`	`string`
`value`	`string`

well_known required

object

Field	Type	Description
`url`	`string`
`body`	`object`

reverified_every_hours required 24

did_document_url required string

`VerifyRequest`object#

Field	Type	Description
`grant` required	`string`	Grant compact JWS as received in Delegus-Grant.
`proof` required	`string`	Proof compact JWS as received in Delegus-Proof.
`action` required	`Action`

Verify#

POST /verify#

Request body · VerifyRequest

Responses

Principal#

POST /revoke#

Parameters

Request body · RevokeRequest

Responses

GET /grants#

Parameters

Responses

POST /grants#

Request body · GrantAllocationRequest

Responses

POST /agents#

Parameters

Request body · AgentRequest

Responses

POST /agents/{did}/disable#

Parameters

Responses

POST /keys/{kid}/compromise#

Parameters

Responses

POST /keys/{kid}/retire#

Parameters

Responses

GET /principals#

Parameters

Responses

GET /principals/{did}#

Parameters

Responses

PATCH /principals/{did}#

Parameters

Request body · PrincipalNamingRequest

Responses

POST /principals/{did}/verify#

Parameters

Responses

GET /grants/{id}/consumption#

Parameters

Responses

Decisions#

GET /decisions#

Parameters

Responses

GET /decisions/{receipt_id}#

Parameters

Responses

POST /decisions/{receipt_id}/outcomes#

Parameters

Request body · OutcomeEvent

Responses

GET /decisions/export#

Parameters

Responses

GET /decisions/stats#

Parameters

Responses

Public#

GET /healthz#

Responses

GET /evidence/{hash}#

Parameters

Responses

GET /status-lists/{path}#

Parameters

Responses

GET /.well-known/did.json#

Responses

GET /org/{slug}/did.json#

Parameters

Responses

Onboarding#

POST /principals#

Request body · PrincipalCreateRequest

Responses

POST `/verify`#

Request body · `VerifyRequest`

POST `/revoke`#

Request body · `RevokeRequest`

GET `/grants`#

POST `/grants`#

Request body · `GrantAllocationRequest`

POST `/agents`#

Request body · `AgentRequest`

POST `/agents/{did}/disable`#

POST `/keys/{kid}/compromise`#

POST `/keys/{kid}/retire`#

GET `/principals`#

GET `/principals/{did}`#

PATCH `/principals/{did}`#

Request body · `PrincipalNamingRequest`

POST `/principals/{did}/verify`#

GET `/grants/{id}/consumption`#

GET `/decisions`#

GET `/decisions/{receipt_id}`#

POST `/decisions/{receipt_id}/outcomes`#

Request body · `OutcomeEvent`

GET `/decisions/export`#

GET `/decisions/stats`#

GET `/healthz`#

GET `/evidence/{hash}`#

GET `/status-lists/{path}`#

GET `/.well-known/did.json`#

GET `/org/{slug}/did.json`#

POST `/principals`#

Request body · `PrincipalCreateRequest`

POST `/relying-parties`#

Request body · `RelyingPartyCreateRequest`

GET `/relying-parties/{did}`#

PATCH `/relying-parties/{did}`#

Request body · `RelyingPartyUpdateRequest`

POST `/orgs/self-serve`#

Request body · `SelfServeRequest`

POST `/orgs/self-serve/starter`#

Request body · `SelfServeRpRequest`

POST `/orgs/self-serve/first-receipt`#

Request body · `SelfServeRpRequest`

GET `/demo/info`#

POST `/demo/mint`#

Request body · `DemoMintRequest`

POST `/demo/verify`#

Request body · `VerifyRequest`

POST `/demo/revoke`#

Request body · `RevokeRequest`

GET `/me`#

GET `/api-keys`#

POST `/api-keys`#

Request body · `ApiKeyRequest`

POST `/api-keys/{key_id}/revoke`#

GET `/audit`#

GET `/usage`#

POST `/orgs`#

Request body · `OrgCreateRequest`

GET `/orgs/{org_id}`#

POST `/orgs/{org_id}/members`#

Request body · `OrgMemberRequest`

GET `/orgs/{org_id}/api-keys`#

POST `/orgs/{org_id}/api-keys`#

Request body · `OrgApiKeyRequest`