{ "openapi": "3.1.0", "info": { "title": "Delegus API", "version": "0.2", "summary": "Verifies an AI agent's delegated authority to act (spec v0.2).", "description": "The /verify response body is always the signed Receipt (spec \u00a75.6), for ALLOW and DENY alike; DENY reasons are documented at https://delegus.ai/docs/reasons. Errors outside evaluation are {error, message}. Grants and Proofs are compact JWS strings exactly as received. Rate limits (per node, one-minute windows): /verify per API key at the relying party's own limit (default 600), 120 other authenticated calls per key, 300 public calls per client IP, 20 failed authentications per IP; responses carry RateLimit-Limit/Remaining/Reset and a 429 {error: \"RATE_LIMITED\"} carries Retry-After.", "contact": { "email": "hello@delegus.ai" } }, "servers": [ { "url": "https://api.delegus.ai", "description": "production" }, { "url": "https://api.dev.delegus.ai", "description": "development" } ], "tags": [ { "name": "verify", "description": "The one call a relying party makes (\u00a75)." }, { "name": "principal", "description": "Grant lifecycle, agents and keys; authenticated as the issuing Principal." }, { "name": "api-keys", "description": "Rotate and revoke API keys: self-service with any live key of the subject, or by admin with ?subject=. A new key does not invalidate the old one; revoke explicitly." }, { "name": "decisions", "description": "Receipts and Outcome Attestations (\u00a79)." }, { "name": "public", "description": "Unauthenticated: evidence by hash (\u00a78), status lists (\u00a77), DID documents." }, { "name": "onboarding", "description": "Registry administration." }, { "name": "sandbox", "description": "Present only when DELEGUS_DEMO=1 (development). Real receipts against an ephemeral sandbox Principal, Agent and relying party." }, { "name": "audit", "description": "Append-only audit of administrative and Principal actions. Verify decisions are receipts, not audit events." }, { "name": "usage", "description": "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." }, { "name": "orgs", "description": "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." }, { "name": "transparency", "description": "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 \u2016 receipt_id); node = SHA-256(0x01 \u2016 left \u2016 right). Anyone recomputes a root from the published leaf hashes; a receipt holder proves inclusion of their receipt id. Also served on status./checkpoints/\u2026 ." }, { "name": "authzen", "description": "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." }, { "name": "metrics", "description": "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." }, { "name": "conformance", "description": "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." } ], "components": { "securitySchemes": { "rpKey": { "type": "http", "scheme": "bearer", "description": "Relying-party API key (dk_rp_\u2026), resolves to the RP DID (\u00a72.3)." }, "principalKey": { "type": "http", "scheme": "bearer", "description": "Principal API key (dk_principal_\u2026), issued at onboarding." }, "adminToken": { "type": "http", "scheme": "bearer", "description": "Delegus admin token (DELEGUS_ADMIN_TOKEN)." }, "orgKey": { "type": "http", "scheme": "bearer", "description": "Organization API key (dk_org_read_\u2026 or dk_org_admin_\u2026), issued at POST /orgs/{org_id}/api-keys. Reads everything about the org's Principals and relying parties; org:admin also administers them. Never accepted by POST /verify or POST /grants." }, "observerKey": { "type": "http", "scheme": "bearer", "description": "Observer API key (dk_observer_\u2026), admin-issued: service-wide read of GET /decisions/stats and GET /usage only." }, "provisionKey": { "type": "http", "scheme": "bearer", "description": "Self-serve provision key (DELEGUS_PROVISION_KEY), held only by the Delegus console. It can provision a new tenant, mint its starter, and set an org's production entitlement; nothing else. The service accepts a comma-separated overlap set so the secret rotates with no downtime." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "PAYLOAD_TOO_LARGE", "SERVICE_UNAVAILABLE", "METHOD_NOT_ALLOWED", "INTERNAL", "RATE_LIMITED" ] }, "message": { "type": "string" } } }, "ReasonCode": { "type": "string", "description": "DENY reason codes in the order of spec \u00a75.2 (protocol), then \u00a75.3 (trust), then reserved.", "enum": [ "GRANT_MALFORMED", "UNSUPPORTED_FEATURE", "ISSUER_KEY_NOT_FOUND", "GRANT_SIGNATURE_INVALID", "GRANT_NOT_YET_VALID", "GRANT_EXPIRED", "AUTHORITY_REVOKED", "AUDIENCE_MISMATCH", "PROOF_MALFORMED", "PROOF_SIGNATURE_INVALID", "PROOF_AGENT_MISMATCH", "PROOF_GRANT_MISMATCH", "PROOF_AUDIENCE_MISMATCH", "PROOF_EXPIRED", "PROOF_ACTION_MISMATCH", "ACTION_MALFORMED", "ACTION_NOT_AUTHORIZED", "UNKNOWN_CONSTRAINT", "CURRENCY_NOT_AUTHORIZED", "AMOUNT_EXCEEDS_AUTHORITY", "RESOURCE_NOT_AUTHORIZED", "ISSUER_UNKNOWN", "ISSUER_UNVERIFIED", "ISSUER_KEY_COMPROMISED", "PROOF_REPLAYED", "SERVICE_UNAVAILABLE", "ISSUER_NOT_TRUSTED" ] }, "ProtocolCheckId": { "type": "string", "enum": [ "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9", "P10", "P11", "P12", "P13", "P14", "P15", "P16", "P17", "P18", "P19", "P20" ] }, "TrustCheckId": { "type": "string", "enum": [ "T1", "T2", "T3", "T5" ] }, "CheckOutcome": { "description": "Check outcome: true, false, or \"skipped\" when a prerequisite did not pass.", "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "skipped" ] } ] }, "Sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "DidWeb": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "DidKey": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" }, "GrantId": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "Action": { "description": "The RP's description of the action (\u00a73.3, \u00a75.1). Integers only, no floats.", "oneOf": [ { "type": "object", "required": [ "type", "resource", "amount", "currency" ], "additionalProperties": false, "properties": { "type": { "const": "commerce:purchase" }, "resource": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "minimum": 0, "description": "minor units" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } } }, { "type": "object", "required": [ "type", "method", "resource" ], "additionalProperties": false, "properties": { "type": { "const": "api:call" }, "method": { "type": "string", "pattern": "^[A-Z]{1,32}$" }, "resource": { "type": "string", "pattern": "^https?://" } } } ] }, "Capability": { "type": "object", "required": [ "action", "constraints" ], "additionalProperties": false, "properties": { "action": { "type": "string", "enum": [ "commerce:purchase", "api:call" ] }, "constraints": { "type": "object", "description": "commerce:purchase: maxAmount (integer, minor units), currency (ISO 4217). api:call: methods (uppercase HTTP methods). Unknown keys deny at P17." }, "resources": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Globs with * and ** only; absent = [\"*\"]." } } }, "VerifyRequest": { "type": "object", "required": [ "grant", "proof", "action" ], "additionalProperties": false, "properties": { "grant": { "type": "string", "description": "Grant compact JWS as received in Delegus-Grant." }, "proof": { "type": "string", "description": "Proof compact JWS as received in Delegus-Proof." }, "action": { "$ref": "#/components/schemas/Action" } } }, "Receipt": { "type": "object", "description": "Decision Receipt (spec \u00a76.2). `receipt` is the canonical non-detached compact JWS over JCS(body minus receipt).", "required": [ "receipt_version", "receipt_id", "decision", "reason", "evaluated_at", "relying_party", "grant_hash", "proof_hash", "evidence", "protocol", "trust", "receipt" ], "properties": { "receipt_version": { "const": "delegus-receipt-v1" }, "receipt_id": { "type": "string", "pattern": "^drc_[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "decision": { "type": "string", "enum": [ "ALLOW", "DENY" ] }, "reason": { "oneOf": [ { "$ref": "#/components/schemas/ReasonCode" }, { "type": "null" } ] }, "evaluated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "relying_party": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "principal": { "type": "object", "required": [ "id", "verification" ], "properties": { "id": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "verification": { "type": "string", "enum": [ "domain", "unverified" ] } }, "description": "Present only once P3 passed (\u00a76.4)." }, "agent": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" }, "grant_id": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "grant_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "proof_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "request_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "authority": { "oneOf": [ { "$ref": "#/components/schemas/Capability" }, { "type": "null" } ], "description": "The Capability that authorized the action; null on DENY; absent before P3." }, "expires_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "evidence": { "type": "object", "required": [ "trust_config_version", "trust_config_hash" ], "properties": { "issuer_resolution": { "type": "object", "required": [ "did", "did_document_hash", "resolved_at" ], "properties": { "did": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "did_document_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "resolved_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" } } }, "status": { "type": "object", "required": [ "credential_url", "credential_hash", "checked_at", "status_list_index" ], "properties": { "credential_url": { "type": "string", "format": "uri" }, "credential_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "valid_from": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "checked_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "status_list_index": { "type": "string" } } }, "trust_config_version": { "type": "string" }, "trust_config_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." } } }, "protocol": { "type": "object", "required": [ "result", "profile", "profile_hash", "checks" ], "properties": { "result": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "profile": { "const": "delegus-base-v1" }, "profile_hash": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$", "description": "The one hash encoding: sha256:<64 lowercase hex> over the exact bytes (spec \u00a76.3)." }, "checks": { "type": "object", "required": [ "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9", "P10", "P11", "P12", "P13", "P14", "P15", "P16", "P17", "P18", "P19", "P20" ], "properties": { "P1": { "$ref": "#/components/schemas/CheckOutcome" }, "P2": { "$ref": "#/components/schemas/CheckOutcome" }, "P3": { "$ref": "#/components/schemas/CheckOutcome" }, "P4": { "$ref": "#/components/schemas/CheckOutcome" }, "P5": { "$ref": "#/components/schemas/CheckOutcome" }, "P6": { "$ref": "#/components/schemas/CheckOutcome" }, "P7": { "$ref": "#/components/schemas/CheckOutcome" }, "P8": { "$ref": "#/components/schemas/CheckOutcome" }, "P9": { "$ref": "#/components/schemas/CheckOutcome" }, "P10": { "$ref": "#/components/schemas/CheckOutcome" }, "P11": { "$ref": "#/components/schemas/CheckOutcome" }, "P12": { "$ref": "#/components/schemas/CheckOutcome" }, "P13": { "$ref": "#/components/schemas/CheckOutcome" }, "P14": { "$ref": "#/components/schemas/CheckOutcome" }, "P15": { "$ref": "#/components/schemas/CheckOutcome" }, "P16": { "$ref": "#/components/schemas/CheckOutcome" }, "P17": { "$ref": "#/components/schemas/CheckOutcome" }, "P18": { "$ref": "#/components/schemas/CheckOutcome" }, "P19": { "$ref": "#/components/schemas/CheckOutcome" }, "P20": { "$ref": "#/components/schemas/CheckOutcome" } } } } }, "trust": { "type": "object", "required": [ "result", "policy_version", "checks" ], "properties": { "result": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "policy_version": { "const": "delegus-trust-v1" }, "checks": { "type": "object", "required": [ "T1", "T2", "T3", "T5" ], "properties": { "T1": { "$ref": "#/components/schemas/CheckOutcome" }, "T2": { "$ref": "#/components/schemas/CheckOutcome" }, "T3": { "$ref": "#/components/schemas/CheckOutcome" }, "T5": { "$ref": "#/components/schemas/CheckOutcome" } } } } }, "receipt": { "type": "string", "description": "Compact JWS, alg EdDSA, typ delegus-receipt+jwt, kid did:web:#receipt-." } } }, "RevokeRequest": { "type": "object", "required": [ "grant_id" ], "properties": { "grant_id": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" } } }, "RevokeResponse": { "type": "object", "required": [ "grant_id", "revoked", "revoked_at" ], "properties": { "grant_id": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "revoked": { "const": true }, "revoked_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" } } }, "GrantAllocationRequest": { "type": "object", "required": [ "agent" ], "properties": { "agent": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" } } }, "CredentialStatus": { "type": "object", "required": [ "id", "type", "statusPurpose", "statusListIndex", "statusListCredential" ], "properties": { "id": { "type": "string" }, "type": { "const": "BitstringStatusListEntry" }, "statusPurpose": { "const": "revocation" }, "statusListIndex": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$" }, "statusListCredential": { "type": "string", "format": "uri" } } }, "GrantAllocation": { "type": "object", "required": [ "id", "issuer", "agent", "credentialStatus", "allocated_at" ], "properties": { "id": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "issuer": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "agent": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" }, "credentialStatus": { "$ref": "#/components/schemas/CredentialStatus" }, "allocated_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" } }, "description": "The Principal signs these into the Grant (\u00a73.2 rows 6 and 14)." }, "AgentRequest": { "type": "object", "required": [ "did" ], "properties": { "did": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" } } }, "Agent": { "type": "object", "required": [ "did", "principal", "created_at" ], "properties": { "did": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" }, "principal": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" } } }, "AgentDisabled": { "type": "object", "required": [ "did", "disabled_at", "revoked_grants" ], "properties": { "did": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" }, "disabled_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "revoked_grants": { "type": "array", "items": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" } } } }, "KeyCompromised": { "type": "object", "required": [ "kid", "state" ], "properties": { "kid": { "type": "string" }, "state": { "const": "compromised" } } }, "Verification": { "type": "object", "required": [ "state", "token", "dns_txt", "well_known", "reverified_every_hours", "did_document_url" ], "properties": { "state": { "type": "string", "enum": [ "verified", "unverified" ] }, "token": { "type": "string" }, "dns_txt": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "well_known": { "type": "object", "properties": { "url": { "type": "string" }, "body": { "type": "object" } } }, "reverified_every_hours": { "const": 24 }, "did_document_url": { "type": "string" } } }, "Principal": { "type": "object", "required": [ "did", "kind", "domain", "verification", "created_at" ], "properties": { "did": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "kind": { "type": "string", "enum": [ "managed", "hosted" ] }, "domain": { "type": "string" }, "verification": { "$ref": "#/components/schemas/Verification" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "org_id": { "oneOf": [ { "$ref": "#/components/schemas/OrgId" }, { "type": "null" } ] }, "may_be_named": { "type": "boolean", "description": "consent to be named publicly (metrics page); default false, admin-set" } } }, "PrincipalCreateRequest": { "oneOf": [ { "type": "object", "required": [ "kind", "slug", "keys" ], "properties": { "kind": { "const": "managed" }, "slug": { "type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" }, "keys": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "required": [ "publicKeyMultibase" ], "properties": { "id": { "type": "string", "description": "fragment, default key-" }, "publicKeyMultibase": { "type": "string", "pattern": "^z6Mk" } } } }, "org_id": { "$ref": "#/components/schemas/OrgId", "description": "admin: attach to this org; org:admin keys always onboard into their own org" } } }, { "type": "object", "required": [ "kind", "did" ], "properties": { "kind": { "const": "hosted" }, "did": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "org_id": { "$ref": "#/components/schemas/OrgId", "description": "admin: attach to this org; org:admin keys always onboard into their own org" } } } ] }, "PrincipalCreated": { "allOf": [ { "$ref": "#/components/schemas/Principal" }, { "type": "object", "required": [ "did_document_resolved", "api_key", "api_key_id" ], "properties": { "did_document_resolved": { "type": "boolean" }, "api_key": { "type": "string", "description": "Shown once." }, "api_key_id": { "type": "string" } } } ] }, "RelyingPartyCreateRequest": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "managed", "hosted" ] }, "slug": { "type": "string" }, "did": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "name": { "type": "string" }, "proof_window_seconds": { "type": "integer", "minimum": 1, "maximum": 300, "default": 60 }, "verify_rate_limit_per_minute": { "type": "integer", "minimum": 1, "maximum": 1000000, "default": 600, "description": "/verify requests per minute per API key (per node)" }, "org_id": { "$ref": "#/components/schemas/OrgId", "description": "admin: attach to this org; org:admin keys always onboard into their own org" }, "profile": { "type": "string", "enum": [ "delegus-base-v1", "delegus-base-v2" ], "description": "default delegus-base-v1" } } }, "RelyingPartyCreated": { "type": "object", "required": [ "did", "name", "proof_window_seconds", "created_at", "api_key", "api_key_id", "verify_rate_limit_per_minute" ], "properties": { "did": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "name": { "type": "string" }, "proof_window_seconds": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "api_key": { "type": "string", "description": "Shown once." }, "api_key_id": { "type": "string" }, "verify_rate_limit_per_minute": { "type": "integer" } } }, "OutcomeEvent": { "type": "object", "required": [ "type", "occurred_at" ], "properties": { "type": { "type": "string", "enum": [ "fulfilled", "cancelled", "dispute_opened", "dispute_resolved", "chargeback_received", "chargeback_reversed", "loss_reported" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "evidence_ref": { "type": "string" }, "note": { "type": "string" }, "correction_of": { "type": "string", "pattern": "^oat_" }, "reporter_signature": { "type": "string" }, "resolution": { "type": "string", "enum": [ "agent_at_fault", "agent_not_at_fault", "indeterminate" ], "description": "required for dispute_resolved" }, "loss_amount": { "type": "integer", "minimum": 0, "description": "required for loss_reported; minor units" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "required for loss_reported" } }, "description": "Unknown fields and unknown types are rejected (\u00a79.3)." }, "Attestation": { "allOf": [ { "$ref": "#/components/schemas/OutcomeEvent" }, { "type": "object", "required": [ "attestation_id", "reporter", "recorded_at" ], "properties": { "attestation_id": { "type": "string", "pattern": "^oat_" }, "reporter": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "recorded_at": { "type": "string", "format": "date-time", "description": "RFC 3339 UTC" }, "consumption": { "type": "object", "required": [ "cause", "version" ], "properties": { "cause": { "type": "string", "enum": [ "restore", "restore_reversal" ] }, "version": { "type": "integer" } }, "description": "Present when this attestation moved the Grant's consumption (v0.3): a cancelled outcome restores the receipt's budget once; a correction of it takes it back" } } } ] }, "Decision": { "type": "object", "required": [ "receipt", "outcomes" ], "properties": { "receipt": { "$ref": "#/components/schemas/Receipt" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/Attestation" } } } }, "DidDocument": { "type": "object", "required": [ "@context", "id", "verificationMethod" ], "properties": { "@context": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "verificationMethod": { "type": "array", "items": { "type": "object", "required": [ "id", "type", "controller", "publicKeyMultibase" ], "properties": { "id": { "type": "string" }, "type": { "const": "Multikey" }, "controller": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "publicKeyMultibase": { "type": "string" } } } }, "assertionMethod": { "type": "array", "items": { "type": "string" } } } }, "Health": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" }, "env": { "type": "string" }, "did": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" } } }, "DemoMintRequest": { "type": "object", "additionalProperties": false, "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 1000000000, "default": 42700, "description": "minor units; the sandbox Grant allows up to 50000 USD" } } }, "DemoMint": { "type": "object", "required": [ "grant", "proof", "action", "rp", "grant_id", "agent", "principal", "request", "authority", "valid_until", "grant_lifetime_seconds" ], "properties": { "grant": { "type": "string" }, "proof": { "type": "string" }, "action": { "$ref": "#/components/schemas/Action" }, "rp": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "grant_id": { "type": "string", "pattern": "^urn:delegus:grant:[0-7][0-9A-HJKMNP-TV-Z]{25}$" }, "agent": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" }, "principal": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" }, "request": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" } } }, "authority": { "$ref": "#/components/schemas/Capability" }, "valid_until": { "type": "string", "format": "date-time" }, "grant_lifetime_seconds": { "type": "integer" } } }, "DemoInfo": { "type": "object", "required": [ "principal", "agent", "rp", "authority", "grant_lifetime_seconds", "request", "amount_cap", "rate_limit_per_minute" ], "properties": { "principal": { "$ref": "#/components/schemas/DidWeb" }, "agent": { "$ref": "#/components/schemas/DidKey" }, "rp": { "$ref": "#/components/schemas/DidWeb" }, "authority": { "$ref": "#/components/schemas/Capability" }, "grant_lifetime_seconds": { "type": "integer" }, "request": { "type": "object", "properties": { "method": { "type": "string" }, "url": { "type": "string" } } }, "amount_cap": { "type": "integer" }, "rate_limit_per_minute": { "type": "integer" } } }, "ApiKey": { "type": "object", "required": [ "key_id", "role", "subject", "label", "created_at", "revoked_at" ], "properties": { "key_id": { "type": "string", "description": "Public identifier (first 12 hex chars of the key hash); never a secret." }, "role": { "type": "string", "enum": [ "principal", "rp", "org:read", "org:admin", "observer" ] }, "subject": { "type": "string", "description": "The Principal or relying-party DID, or the org id for org keys" }, "label": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "ApiKeyIssued": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string", "description": "Shown once." } } } ] }, "ApiKeyList": { "type": "object", "required": [ "subject", "keys" ], "properties": { "subject": { "$ref": "#/components/schemas/DidWeb" }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "ApiKeyRequest": { "type": "object", "additionalProperties": false, "properties": { "label": { "type": "string", "maxLength": 100 } } }, "Me": { "type": "object", "required": [ "subject", "role", "key_id", "service_did", "env" ], "properties": { "subject": { "type": "string", "description": "DID, or org id for org keys" }, "role": { "type": "string", "enum": [ "principal", "rp", "org:read", "org:admin", "observer" ] }, "key_id": { "type": "string" }, "key_label": { "type": [ "string", "null" ] }, "key_created_at": { "type": "string", "format": "date-time" }, "service_did": { "$ref": "#/components/schemas/DidWeb" }, "env": { "type": "string" }, "name": { "type": "string", "description": "relying parties" }, "proof_window_seconds": { "type": "integer", "description": "relying parties" }, "kind": { "type": "string", "enum": [ "managed", "hosted" ], "description": "principals" }, "verification": { "$ref": "#/components/schemas/Verification" }, "keys": { "type": "array", "items": { "type": "object", "properties": { "kid": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "retired", "compromised" ] } } }, "description": "principals: signing keys known from the DID document and their trust state" }, "org_id": { "oneOf": [ { "$ref": "#/components/schemas/OrgId" }, { "type": "null" } ], "description": "Principals and relying parties: their org" }, "org": { "$ref": "#/components/schemas/Org", "description": "org keys" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMember" }, "description": "org keys" }, "scope": { "type": "array", "items": { "type": "string" }, "description": "observer keys: the endpoints the key may call" } } }, "DecisionSummary": { "type": "object", "required": [ "receipt_id", "decision", "reason", "evaluated_at", "principal", "grant_id", "agent", "rp", "key_id", "action_type", "amount", "currency", "resource", "method" ], "properties": { "receipt_id": { "type": "string" }, "decision": { "type": "string", "enum": [ "ALLOW", "DENY" ] }, "reason": { "oneOf": [ { "$ref": "#/components/schemas/ReasonCode" }, { "type": "null" } ] }, "evaluated_at": { "type": "string", "format": "date-time" }, "principal": { "oneOf": [ { "$ref": "#/components/schemas/DidWeb" }, { "type": "null" } ] }, "grant_id": { "oneOf": [ { "$ref": "#/components/schemas/GrantId" }, { "type": "null" } ] }, "agent": { "oneOf": [ { "$ref": "#/components/schemas/DidKey" }, { "type": "null" } ] }, "rp": { "$ref": "#/components/schemas/DidWeb" }, "key_id": { "oneOf": [ { "$ref": "#/components/schemas/ApiKeyId" }, { "type": "null" } ], "description": "The relying-party key that made the verify; null before key tracking" }, "action_type": { "oneOf": [ { "type": "string", "enum": [ "commerce:purchase", "api:call" ] }, { "type": "null" } ], "description": "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": { "oneOf": [ { "type": "integer" }, { "type": "null" } ], "description": "commerce:purchase: integer minor units of `currency` (JPY has 0 decimals, USD 2, KWD 3). Null otherwise." }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "commerce:purchase: ISO 4217 code. Null otherwise." }, "resource": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The action resource as submitted (a purchase resource or an api:call URI)." }, "method": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "api:call: the HTTP method. Null otherwise." } } }, "DecisionList": { "type": "object", "required": [ "decisions", "next_cursor" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/DecisionSummary" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as ?cursor= for the next (older) page; null when this was the last page." } } }, "AuditEvent": { "type": "object", "required": [ "event_id", "occurred_at", "actor", "action", "target", "request_id", "details" ], "properties": { "event_id": { "type": "string", "pattern": "^aud_" }, "occurred_at": { "type": "string", "format": "date-time" }, "actor": { "type": "object", "required": [ "kind", "did", "key_id" ], "properties": { "kind": { "type": "string", "enum": [ "admin", "principal", "rp", "org", "system" ] }, "did": { "type": [ "string", "null" ], "description": "The subject DID, or the org id for org keys" }, "key_id": { "type": [ "string", "null" ] } } }, "action": { "type": "string", "description": "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": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "details": { "type": "object" } } }, "AuditList": { "type": "object", "required": [ "events", "next_cursor" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "KeyRetired": { "type": "object", "required": [ "kid", "state" ], "properties": { "kid": { "type": "string" }, "state": { "type": "string", "enum": [ "retired", "compromised" ] } } }, "UsageDay": { "type": "object", "required": [ "day", "verifies", "allow", "deny", "reasons" ], "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "UTC day" }, "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" }, "reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "DENY reason \u2192 count" }, "keys": { "type": "object", "additionalProperties": { "type": "object", "required": [ "verifies", "allow", "deny" ], "properties": { "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" } } }, "description": "Present with by=key: per API key id (\"unknown\" for receipts recorded before key tracking)" } } }, "Usage": { "type": "object", "required": [ "since", "until", "totals", "days" ], "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "rp": { "$ref": "#/components/schemas/DidWeb" }, "principal": { "$ref": "#/components/schemas/DidWeb" }, "totals": { "type": "object", "required": [ "verifies", "allow", "deny" ], "properties": { "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" } } }, "days": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDay" } }, "rps": { "type": "array", "items": { "$ref": "#/components/schemas/DidWeb" }, "description": "org keys: the relying parties covered" }, "key_id": { "$ref": "#/components/schemas/ApiKeyId" } } }, "RelyingPartyUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 }, "proof_window_seconds": { "type": "integer", "minimum": 1, "maximum": 300 }, "verify_rate_limit_per_minute": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "profile": { "type": "string", "enum": [ "delegus-base-v1", "delegus-base-v2" ], "description": "default delegus-base-v1" } } }, "RelyingParty": { "type": "object", "required": [ "did", "name", "proof_window_seconds", "verify_rate_limit_per_minute", "created_at" ], "properties": { "did": { "$ref": "#/components/schemas/DidWeb" }, "name": { "type": "string" }, "proof_window_seconds": { "type": "integer" }, "verify_rate_limit_per_minute": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "org_id": { "oneOf": [ { "$ref": "#/components/schemas/OrgId" }, { "type": "null" } ] }, "profile": { "type": "string", "enum": [ "delegus-base-v1", "delegus-base-v2" ], "description": "Protocol profile for /verify; v2 enables consumable grants (budget). Default v1." } } }, "OrgId": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" }, "ApiKeyId": { "type": "string", "pattern": "^[0-9a-f]{12}$", "description": "Public identifier of an API key (first 12 hex chars of its hash); never a secret." }, "Org": { "type": "object", "required": [ "org_id", "slug", "name", "created_at" ], "properties": { "org_id": { "$ref": "#/components/schemas/OrgId" }, "slug": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "OrgCreateRequest": { "type": "object", "required": [ "slug", "name" ], "properties": { "slug": { "type": "string", "description": "lowercase DNS label, unique" }, "name": { "type": "string", "maxLength": 200 } } }, "OrgMember": { "type": "object", "required": [ "did", "kind", "created_at" ], "properties": { "did": { "$ref": "#/components/schemas/DidWeb" }, "kind": { "type": "string", "enum": [ "principal", "relying_party" ] }, "created_at": { "type": "string", "format": "date-time" }, "principal_kind": { "type": "string", "enum": [ "managed", "hosted" ], "description": "principals" }, "domain": { "type": "string", "description": "principals" }, "verification_state": { "type": "string", "enum": [ "verified", "unverified" ], "description": "principals" }, "verification": { "$ref": "#/components/schemas/Verification", "description": "principals" }, "name": { "type": "string", "description": "relying parties" }, "proof_window_seconds": { "type": "integer", "description": "relying parties" }, "verify_rate_limit_per_minute": { "type": "integer", "description": "relying parties" } } }, "OrgWithMembers": { "allOf": [ { "$ref": "#/components/schemas/Org" }, { "type": "object", "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OrgMember" } } } } ] }, "OrgMemberRequest": { "type": "object", "required": [ "did" ], "properties": { "did": { "$ref": "#/components/schemas/DidWeb", "description": "An existing Principal or relying party not yet in another org" } } }, "OrgMemberAdded": { "type": "object", "required": [ "org_id", "did", "kind" ], "properties": { "org_id": { "$ref": "#/components/schemas/OrgId" }, "did": { "$ref": "#/components/schemas/DidWeb" }, "kind": { "type": "string", "enum": [ "principal", "relying_party" ] } } }, "OrgApiKeyRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "read", "admin" ], "description": "read: every GET about the org and its members; admin: also onboarding, keys, revocation, agents, Principal keys, RP settings" }, "label": { "type": "string", "maxLength": 100 } } }, "OrgApiKeyList": { "type": "object", "required": [ "org_id", "keys" ], "properties": { "org_id": { "$ref": "#/components/schemas/OrgId" }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "GrantSummary": { "type": "object", "required": [ "id", "principal", "agent", "status_list", "status_list_index", "allocated_at", "revoked_at", "state" ], "description": "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.", "properties": { "id": { "$ref": "#/components/schemas/GrantId" }, "principal": { "$ref": "#/components/schemas/DidWeb" }, "agent": { "$ref": "#/components/schemas/DidKey" }, "status_list": { "type": "string", "format": "uri" }, "status_list_index": { "type": "integer" }, "allocated_at": { "type": "string", "format": "date-time" }, "revoked_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "revoked" ] } } }, "GrantList": { "type": "object", "required": [ "grants", "next_cursor" ], "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/GrantSummary" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Checkpoint": { "type": "object", "required": [ "day", "tree_size", "root", "previous_root", "first_receipt_id", "last_receipt_id", "tree", "kid", "checkpoint", "checkpoint_hash", "leaves_url", "created_at" ], "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "tree_size": { "type": "integer", "minimum": 0 }, "root": { "$ref": "#/components/schemas/Sha256" }, "previous_root": { "oneOf": [ { "$ref": "#/components/schemas/Sha256" }, { "type": "null" } ], "description": "The previous day's root; null for the first checkpoint" }, "first_receipt_id": { "type": [ "string", "null" ] }, "last_receipt_id": { "type": [ "string", "null" ] }, "tree": { "type": "string", "enum": [ "rfc6962-sha256" ] }, "kid": { "type": "string", "description": "did:web:#status-, the signing key" }, "checkpoint": { "type": "string", "description": "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": { "$ref": "#/components/schemas/Sha256" }, "leaves_url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "InclusionProof": { "type": "object", "required": [ "receipt_id", "day", "leaf", "leaf_index", "tree_size", "root", "audit_path", "checkpoint", "kid" ], "properties": { "receipt_id": { "type": "string" }, "day": { "type": "string" }, "leaf": { "type": "string", "description": "hex SHA-256(0x00 \u2016 receipt_id)" }, "leaf_index": { "type": "integer", "minimum": 0 }, "tree_size": { "type": "integer", "minimum": 1 }, "root": { "$ref": "#/components/schemas/Sha256" }, "audit_path": { "type": "array", "items": { "type": "string" }, "description": "RFC 6962 \u00a72.1.1 audit path, hex, leaf to root" }, "checkpoint": { "type": "string", "description": "The day's checkpoint JWS" }, "kid": { "type": "string" } } }, "InclusionPending": { "type": "object", "required": [ "receipt_id", "day", "status" ], "properties": { "receipt_id": { "type": "string" }, "day": { "type": "string" }, "status": { "type": "string" } } }, "CheckpointsClosed": { "type": "object", "required": [ "closed", "latest" ], "properties": { "closed": { "type": "array", "items": { "type": "string" } }, "latest": { "type": [ "string", "null" ] } } }, "DecisionExportRow": { "allOf": [ { "$ref": "#/components/schemas/DecisionSummary" }, { "type": "object", "required": [ "receipt", "outcomes" ], "properties": { "receipt": { "$ref": "#/components/schemas/Receipt" }, "outcomes": { "type": "array", "items": { "$ref": "#/components/schemas/Attestation" } } } } ], "description": "One NDJSON line: the decision summary, the full signed receipt, and its outcome ledger" }, "PrincipalStats": { "type": "object", "required": [ "principal", "verifies", "allow", "deny", "reasons", "outcomes", "losses", "allow_with_outcome" ], "properties": { "principal": { "oneOf": [ { "$ref": "#/components/schemas/DidWeb" }, { "type": "null" } ], "description": "null groups receipts denied before the Grant was authenticated (P1\u2013P3, T1\u2013T3)" }, "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" }, "reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "DENY reason \u2192 count" }, "outcomes": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "outcome type \u2192 count" }, "losses": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "loss_reported sums per currency, minor units" }, "allow_with_outcome": { "type": "integer", "description": "ALLOW receipts with at least one outcome attestation" } } }, "DecisionStats": { "type": "object", "required": [ "since", "until", "totals", "principals" ], "properties": { "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "rps": { "type": "array", "items": { "$ref": "#/components/schemas/DidWeb" } }, "totals": { "type": "object", "required": [ "verifies", "allow", "deny", "allow_with_outcome" ], "properties": { "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" }, "allow_with_outcome": { "type": "integer" } } }, "principals": { "type": "array", "items": { "$ref": "#/components/schemas/PrincipalStats" } } } }, "PrincipalDirectoryEntry": { "type": "object", "required": [ "did", "kind", "domain", "verification", "keys", "did_document", "registered_at" ], "description": "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.", "properties": { "did": { "$ref": "#/components/schemas/DidWeb" }, "kind": { "type": "string", "enum": [ "managed", "hosted" ] }, "domain": { "type": "string" }, "verification": { "type": "object", "required": [ "state", "verified_since", "last_checked_at", "method" ], "properties": { "state": { "type": "string", "enum": [ "verified", "unverified" ] }, "verified_since": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "last_checked_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "method": { "type": "string", "enum": [ "domain", "delegus-hosted" ], "description": "domain: DNS TXT or .well-known proof, re-checked every 24 h; delegus-hosted: managed Principal, verified by construction" } } }, "keys": { "type": "array", "items": { "type": "object", "required": [ "kid", "state", "since" ], "properties": { "kid": { "type": "string" }, "state": { "type": "string", "enum": [ "active", "retired", "compromised" ] }, "since": { "type": "string", "format": "date-time" } } }, "description": "Key history: every verification method ever seen, with its current state" }, "did_document": { "oneOf": [ { "type": "object", "required": [ "hash", "resolved_at" ], "properties": { "hash": { "$ref": "#/components/schemas/Sha256" }, "resolved_at": { "type": "string", "format": "date-time" } } }, { "type": "null" } ] }, "registered_at": { "type": "string", "format": "date-time" }, "may_be_named": { "type": "boolean", "description": "consent to be named publicly (metrics page); default false, admin-set" } } }, "PrincipalDirectory": { "type": "object", "required": [ "principals", "next_cursor" ], "properties": { "principals": { "type": "array", "items": { "$ref": "#/components/schemas/PrincipalDirectoryEntry" } }, "next_cursor": { "oneOf": [ { "$ref": "#/components/schemas/DidWeb" }, { "type": "null" } ] } } }, "ConsumptionBalance": { "type": "object", "required": [ "key", "spent_total", "spent_in_period", "period_start", "uses_spent", "limits", "remaining", "updated_at" ], "properties": { "key": { "$ref": "#/components/schemas/Sha256", "description": "sha256 over the RFC 8785 form of the Capability (v0.3 proposal \u00a73)" }, "spent_total": { "type": "integer" }, "spent_in_period": { "type": "integer" }, "period_start": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "uses_spent": { "type": "integer" }, "limits": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "per_period": { "type": [ "integer", "null" ] }, "uses": { "type": [ "integer", "null" ] } }, "description": "as seen at the last consume" }, "remaining": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ] }, "per_period": { "type": [ "integer", "null" ] }, "uses": { "type": [ "integer", "null" ] } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "ConsumptionEvent": { "type": "object", "required": [ "version", "key", "delta_total", "delta_period", "delta_uses", "period_start", "cause", "cause_id", "receipt_id", "recorded_at" ], "properties": { "version": { "type": "integer" }, "key": { "$ref": "#/components/schemas/Sha256" }, "delta_total": { "type": "integer" }, "delta_period": { "type": "integer" }, "delta_uses": { "type": "integer" }, "period_start": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cause": { "type": "string", "enum": [ "consume", "restore", "restore_reversal" ] }, "cause_id": { "type": "string", "description": "receipt id (consume) or attestation id (restore, restore_reversal)" }, "receipt_id": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time" } } }, "GrantConsumption": { "type": "object", "required": [ "grant_id", "principal", "agent", "version", "as_of", "snapshot_hash", "capabilities", "events", "next_cursor" ], "description": "Balances and the append-only consumption log of one Grant (v0.3 consumable Grants, proposal \u00a77\u2013\u00a78). Empty for Grants that were never consumed.", "properties": { "grant_id": { "$ref": "#/components/schemas/GrantId" }, "principal": { "$ref": "#/components/schemas/DidWeb" }, "agent": { "$ref": "#/components/schemas/DidKey" }, "version": { "type": "integer", "description": "log version; 0 when never consumed" }, "as_of": { "type": "string", "format": "date-time" }, "snapshot_hash": { "$ref": "#/components/schemas/Sha256", "description": "hash of the canonical consumption snapshot as of now (what a v0.3 receipt would pin)" }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionBalance" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ConsumptionEvent" }, "description": "newest first" }, "next_cursor": { "type": [ "integer", "null" ] } } }, "AuthZenEntity": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "properties": { "type": "object", "additionalProperties": true } } }, "AuthZenRequest": { "type": "object", "required": [ "subject", "action", "resource" ], "properties": { "subject": { "allOf": [ { "$ref": "#/components/schemas/AuthZenEntity" } ], "description": "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": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "enum": [ "commerce:purchase", "api:call" ] }, "properties": { "type": "object", "additionalProperties": true, "description": "the remaining Delegus Action fields: amount, currency (commerce:purchase) or method (api:call); never type or resource" } } }, "resource": { "allOf": [ { "$ref": "#/components/schemas/AuthZenEntity" } ], "description": "id = the Delegus action.resource (order id or absolute URL)" }, "context": { "type": "object", "additionalProperties": true } }, "example": { "subject": { "type": "agent", "id": "did:key:z6Mk\u2026", "properties": { "grant": "eyJ\u2026", "proof": "eyJ\u2026" } }, "action": { "name": "commerce:purchase", "properties": { "amount": 42700, "currency": "USD" } }, "resource": { "type": "order", "id": "order_92813" }, "context": { "agent": "did:key:z6Mk\u2026" } } }, "AuthZenResponse": { "type": "object", "required": [ "decision", "context" ], "properties": { "decision": { "type": "boolean", "description": "true iff the Delegus receipt says ALLOW" }, "context": { "type": "object", "required": [ "reason", "receipt_id", "evaluated_at", "relying_party", "receipt", "receipt_url", "issuer" ], "properties": { "reason": { "oneOf": [ { "$ref": "#/components/schemas/ReasonCode" }, { "type": "null" } ] }, "receipt_id": { "type": "string" }, "evaluated_at": { "type": "string", "format": "date-time" }, "relying_party": { "$ref": "#/components/schemas/DidWeb" }, "principal": { "$ref": "#/components/schemas/DidWeb" }, "agent": { "$ref": "#/components/schemas/DidKey" }, "receipt": { "type": "string", "description": "the signed receipt JWS" }, "receipt_url": { "type": "string" }, "issuer": { "$ref": "#/components/schemas/DidWeb" } } } } }, "AuthZenConfiguration": { "type": "object", "required": [ "policy_decision_point", "access_evaluation_endpoint" ], "properties": { "policy_decision_point": { "type": "string", "format": "uri" }, "access_evaluation_endpoint": { "type": "string", "format": "uri" }, "delegus": { "type": "object", "additionalProperties": { "type": "string" } } } }, "Metrics": { "type": "object", "required": [ "as_of", "service_did", "env", "principals", "relying_parties", "organizations", "receipts_total", "verifies", "transparency", "named_principals", "self_test" ], "description": "Aggregate only; no Principal, relying-party or receipt identifiers appear.", "properties": { "as_of": { "type": "string", "format": "date-time" }, "service_did": { "$ref": "#/components/schemas/DidWeb" }, "env": { "type": "string" }, "principals": { "type": "object", "required": [ "verified", "hosted_verified", "hosted_unverified", "managed" ], "properties": { "verified": { "type": "integer" }, "hosted_verified": { "type": "integer" }, "hosted_unverified": { "type": "integer" }, "managed": { "type": "integer" } } }, "relying_parties": { "type": "integer" }, "organizations": { "type": "integer" }, "receipts_total": { "type": "integer" }, "verifies": { "type": "object", "required": [ "window_days", "since", "until", "verifies", "allow", "deny", "per_day" ], "properties": { "window_days": { "type": "integer" }, "since": { "type": "string", "format": "date-time" }, "until": { "type": "string", "format": "date-time" }, "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" }, "per_day": { "type": "array", "items": { "type": "object", "required": [ "day", "verifies", "allow", "deny" ], "properties": { "day": { "type": "string" }, "verifies": { "type": "integer" }, "allow": { "type": "integer" }, "deny": { "type": "integer" } } } } } }, "transparency": { "type": "object", "properties": { "latest_day": { "type": [ "string", "null" ] }, "latest_root": { "$ref": "#/components/schemas/Sha256" }, "latest_tree_size": { "type": "integer" }, "checkpoints": { "type": "integer" } } }, "named_principals": { "type": "array", "items": { "type": "object", "required": [ "did", "domain", "kind" ], "properties": { "did": { "$ref": "#/components/schemas/DidWeb" }, "domain": { "type": "string" }, "kind": { "type": "string", "enum": [ "managed", "hosted" ] } } }, "description": "verified Principals that opted in to public naming" }, "self_test": { "type": "object", "required": [ "principals", "relying_parties", "organizations" ], "properties": { "principals": { "type": "integer" }, "relying_parties": { "type": "integer" }, "organizations": { "type": "integer" } }, "description": "self-test/liveness tenants, excluded from the customer counters above; never a customer" } } }, "PrincipalNamingRequest": { "type": "object", "required": [ "may_be_named" ], "properties": { "may_be_named": { "type": "boolean" } } }, "SelfServeRequest": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "admin_email" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "Lowercase DNS label; becomes the org slug and the managed relying party did:web::rp:. Taken or reserved slugs are 409." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "admin_email": { "type": "string", "format": "email", "maxLength": 200 } } }, "SelfServeStarter": { "type": "object", "required": [ "grant", "proof", "action", "grant_id", "expires_at", "verify_url", "verify_curl" ], "description": "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.", "properties": { "grant": { "type": "string", "description": "Grant compact JWS (vc+jwt)." }, "proof": { "type": "string", "description": "Proof compact JWS (delegus-proof+jwt), aud = this relying party." }, "action": { "type": "object", "description": "The exact Action the Proof is bound to (a $10.00 sandbox purchase)." }, "grant_id": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the Proof leaves the relying party's 300-second window; call /orgs/self-serve/starter for a fresh one." }, "verify_url": { "type": "string", "format": "uri" }, "verify_curl": { "type": "string", "description": "A ready shell command for /verify; the literal marks where the customer's key goes." } } }, "SelfServeBundle": { "type": "object", "required": [ "org", "org_admin_key", "relying_party", "rp_verify_key", "starter" ], "properties": { "org": { "$ref": "#/components/schemas/Org" }, "org_admin_key": { "type": "string", "description": "org:admin key for the new org (dk_org_admin_\u2026). Shown once; the console keeps it server-side and never shows it to the customer." }, "relying_party": { "type": "object", "required": [ "did", "name", "profile", "proof_window_seconds" ], "properties": { "did": { "type": "string" }, "name": { "type": "string" }, "profile": { "type": "string" }, "proof_window_seconds": { "type": "integer" } }, "description": "The tenant's managed relying party. Managed identities are verified at creation; nothing is pending." }, "rp_verify_key": { "type": "string", "description": "The customer's first relying-party verify key (dk_rp_\u2026). Shown once." }, "starter": { "$ref": "#/components/schemas/SelfServeStarter" } } }, "SelfServeRpRequest": { "type": "object", "additionalProperties": false, "required": [ "rp_did" ], "properties": { "rp_did": { "type": "string", "description": "A managed relying party created by POST /orgs/self-serve." } } }, "ConformanceRunRequest": { "type": "object", "additionalProperties": false, "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string", "format": "uri", "maxLength": 2048, "description": "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." } } }, "ConformanceRun": { "type": "object", "required": [ "run_id", "status", "endpoint", "created_at", "finished_at", "requests", "vectors", "error", "report", "signed" ], "properties": { "run_id": { "type": "string", "description": "cfr_" }, "status": { "type": "string", "enum": [ "running", "passed", "failed", "error" ], "description": "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": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "requests": { "type": "integer", "description": "Requests sent to the endpoint (at most 50 per run)." }, "vectors": { "type": "object", "required": [ "sha256", "conformance_version" ], "properties": { "sha256": { "type": "string", "description": "sha256 over the vector set that ran (recompute with vectorSetHash())." }, "conformance_version": { "type": "string" } } }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "report": { "oneOf": [ { "type": "object", "description": "The runner report: per-vector pass/fail with the first mismatch, the committed-receipt re-verification (always done by @delegus/core in the runner, never by the endpoint), the htu/jcs/jti sets, a summary, and the wire pin." }, { "type": "null" } ] }, "signed": { "type": "boolean", "enum": [ false ], "description": "Reports are unsigned in v1." } } }, "EntitlementRequest": { "type": "object", "additionalProperties": false, "required": [ "production", "production_until", "check_cap", "cap_since", "reason", "as_of" ], "properties": { "production": { "type": "string", "enum": [ "allowed", "blocked" ] }, "production_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Production checks stop at this instant; null for no end." }, "check_cap": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000000000, "description": "At most this many production checks since cap_since; null for no cap." }, "cap_since": { "type": [ "string", "null" ], "format": "date-time", "description": "Start of the capped count; required with check_cap. A new value starts a fresh count." }, "reason": { "type": "string", "enum": [ "trial", "paid", "past_due_grace", "canceled", "comp", "none" ] }, "as_of": { "type": "string", "format": "date-time", "description": "The console's change time. At most five minutes ahead of the server clock." } } }, "Entitlement": { "type": "object", "required": [ "org_id", "stored", "effective", "enforced", "comp" ], "properties": { "org_id": { "type": "string" }, "stored": { "type": "boolean", "description": "Whether a row exists. With enforcement on, no row means no plan." }, "production": { "type": [ "string", "null" ], "enum": [ "allowed", "blocked", null ] }, "production_until": { "type": [ "string", "null" ], "format": "date-time" }, "check_cap": { "type": [ "integer", "null" ] }, "cap_since": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": [ "string", "null" ], "enum": [ "trial", "paid", "past_due_grace", "canceled", "comp", "none", null ] }, "as_of": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "production_checks_since_cap": { "type": [ "integer", "null" ], "description": "Production checks counted since cap_since (at most check_cap); null without a cap." }, "comp": { "type": "boolean", "description": "A staff, self-test or canary tenant that never needs a plan." }, "effective": { "type": "string", "enum": [ "allowed", "blocked" ], "description": "What the gate would decide for the next production check now." }, "effective_detail": { "type": [ "string", "null" ], "description": "Why it would be refused; null when allowed." }, "enforced": { "type": "boolean", "description": "Whether this deployment refuses (true) or only logs (false) a blocked production check." }, "applied": { "type": "boolean", "description": "PUT only: whether this push was stored." } } } } }, "paths": { "/healthz": { "get": { "tags": [ "public" ], "summary": "Liveness of every backing service the spec fails closed on", "responses": { "200": { "description": "All backing services reachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "A backing service is unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/verify": { "post": { "tags": [ "verify" ], "summary": "Evaluate a Grant, Proof and Action; returns the signed Receipt", "security": [ { "rpKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "200": { "description": "The Receipt, decision ALLOW or DENY", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Malformed envelope (strings inside it are the engine's business and yield a DENY receipt)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unknown or non-RP API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body over 64 KB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Backing service unavailable before or after evaluation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/revoke": { "post": { "tags": [ "principal" ], "summary": "Revoke a Grant (\u00a77); idempotent; success only once visible everywhere", "security": [ { "principalKey": [] }, { "orgKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeResponse" } } } }, "400": { "description": "Bad grant_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not a Principal key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not this Principal's Grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Revocation recorded but not yet visible; retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)" } ] } }, "/grants": { "post": { "tags": [ "principal" ], "summary": "Reserve a Grant id and its Delegus-signed status entry", "security": [ { "principalKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantAllocationRequest" } } } }, "responses": { "201": { "description": "Allocated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantAllocation" } } } }, "400": { "description": "Bad agent DID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not a Principal key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Agent is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "principal" ], "summary": "Grants allocated by a Principal (ids, agents, status entries, revocation), newest first", "security": [ { "principalKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org keys: one member Principal (default: all of them); admin: any" }, { "name": "agent", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidKey" }, "description": "" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "revoked" ] }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantList" } } } }, "400": { "description": "Bad filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Named Principal is not a member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/agents": { "post": { "tags": [ "principal" ], "summary": "Register an Agent (inventory; not consulted by /verify)", "security": [ { "principalKey": [] }, { "orgKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentRequest" } } } }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Bad DID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not a Principal key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)" } ] } }, "/agents/{did}/disable": { "post": { "tags": [ "principal" ], "summary": "Kill switch: revoke every Grant naming the Agent", "security": [ { "principalKey": [] }, { "orgKey": [] } ], "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^did:key:z6Mk", "example": "did:key:z6MkvRXNYcE7MMduynWTgeKbDaT1iijDSC8pZqXZc8rHPrf2" } }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDisabled" } } } }, "401": { "description": "Not a Principal key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not this Principal's Agent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/keys/{kid}/compromise": { "post": { "tags": [ "principal" ], "summary": "Mark a Principal key compromised (\u00a711)", "security": [ { "principalKey": [] }, { "orgKey": [] } ], "parameters": [ { "name": "kid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded DID URL" }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyCompromised" } } } }, "401": { "description": "Not a Principal key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not this Principal's key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/keys/{kid}/retire": { "post": { "tags": [ "principal" ], "summary": "Retire a Principal key (\u00a711 rotation): existing Grants stay valid to validUntil; new Grants must use an active key", "security": [ { "principalKey": [] }, { "orgKey": [] } ], "parameters": [ { "name": "kid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "URL-encoded DID URL" }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org:admin keys: the member Principal to act for (required for them; a Principal key acts only for itself)" } ], "responses": { "200": { "description": "Retired (idempotent; a compromised key stays compromised)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRetired" } } } }, "401": { "description": "Not a Principal key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Not this Principal's key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/principals": { "post": { "tags": [ "onboarding" ], "summary": "Register a managed or customer-hosted Principal", "security": [ { "adminToken": [] }, { "orgKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalCreateRequest" } } } }, "responses": { "201": { "description": "Registered; API key shown once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalCreated" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bad admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already registered, or a Delegus-managed domain", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "An org:admin key onboards into its own org; admin may pass org_id." }, "get": { "tags": [ "principal" ], "summary": "Principal directory: who is registered and verified, since when, with which keys (any live key or admin)", "security": [ { "rpKey": [] }, { "principalKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "managed", "hosted" ] }, "description": "" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "verified", "unverified" ] }, "description": "" }, { "name": "org_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OrgId" }, "description": "that org's keys or admin only" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "next_cursor from the previous page (ascending DID order)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalDirectory" } } } }, "400": { "description": "Bad filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No live key and no admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "org_id filter by a key of another subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/principals/{did}": { "get": { "tags": [ "principal" ], "summary": "Principal state: the full record with verification instructions for the Principal itself, its org and admin; the directory view for any other live key", "security": [ { "principalKey": [] }, { "adminToken": [] }, { "orgKey": [] }, { "rpKey": [] } ], "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Principal" }, { "$ref": "#/components/schemas/PrincipalDirectoryEntry" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown Principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "principal" ], "summary": "Set the public-naming consent flag (admin)", "security": [ { "adminToken": [] } ], "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^did:web:" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrincipalNamingRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "description": "Bad body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown Principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/principals/{did}/verify": { "post": { "tags": [ "principal" ], "summary": "Run domain verification now", "security": [ { "principalKey": [] }, { "adminToken": [] }, { "orgKey": [] } ], "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown Principal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/relying-parties": { "post": { "tags": [ "onboarding" ], "summary": "Register a relying party; returns its API key once", "security": [ { "adminToken": [] }, { "orgKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelyingPartyCreateRequest" } } } }, "responses": { "201": { "description": "Registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelyingPartyCreated" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bad admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "An org:admin key onboards into its own org; admin may pass org_id." } }, "/relying-parties/{did}": { "patch": { "tags": [ "onboarding" ], "summary": "Update a relying party's name, Proof window or /verify rate limit", "security": [ { "adminToken": [] }, { "orgKey": [] } ], "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/DidWeb" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelyingPartyUpdateRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelyingParty" } } } }, "400": { "description": "Bad field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Bad admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown relying party", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "onboarding" ], "summary": "Relying-party settings", "security": [ { "rpKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "did", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^did:web:", "example": "did:web:acme.example" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelyingParty" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown relying party", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "tags": [ "api-keys" ], "summary": "What the caller's API key resolves to (subject, role, settings); the check behind `delegus doctor`", "security": [ { "principalKey": [] }, { "rpKey": [] }, { "orgKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Unknown or revoked key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api-keys": { "get": { "tags": [ "api-keys" ], "summary": "List the subject's API keys (ids only, never the keys)", "security": [ { "principalKey": [] }, { "rpKey": [] }, { "adminToken": [] }, { "orgKey": [] } ], "parameters": [ { "name": "subject", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "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": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "401": { "description": "No live key and no admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Admin named an unknown subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "api-keys" ], "summary": "Issue an additional API key for the subject (rotation step 1)", "security": [ { "principalKey": [] }, { "rpKey": [] }, { "adminToken": [] }, { "orgKey": [] } ], "parameters": [ { "name": "subject", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "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)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRequest" } } } }, "responses": { "201": { "description": "Issued; the key is shown once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssued" } } } }, "400": { "description": "Bad label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No live key and no admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Admin named an unknown subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api-keys/{key_id}/revoke": { "post": { "tags": [ "api-keys" ], "summary": "Revoke one of the subject's keys by id (rotation step 2, or a leaked key)", "security": [ { "principalKey": [] }, { "rpKey": [] }, { "adminToken": [] }, { "orgKey": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subject", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "Admin only: act on this Principal or relying party instead of the caller's own subject." } ], "responses": { "200": { "description": "Revoked (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "description": "No live key and no admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not one of this subject's keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/audit": { "get": { "tags": [ "audit" ], "summary": "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", "security": [ { "adminToken": [] }, { "principalKey": [] }, { "rpKey": [] }, { "orgKey": [] } ], "parameters": [ { "name": "actor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "admin only: filter by actor DID or org id" }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string" }, "description": "noun.verb" }, { "name": "target", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditList" } } } }, "400": { "description": "Bad filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key and no admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/usage": { "get": { "tags": [ "usage" ], "summary": "Verifies per UTC day over a range (default: the last 30 days)", "security": [ { "rpKey": [] }, { "principalKey": [] }, { "adminToken": [] }, { "orgKey": [] }, { "observerKey": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "inclusive; default 29 days ago at 00:00Z" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "exclusive; default tomorrow 00:00Z; range \u2264 366 days" }, { "name": "rp", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "admin: any; org keys: one member relying party (default: all of them)" }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "admin: any; org keys: one member Principal" }, { "name": "key_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyId" }, "description": "only verifies made with this relying-party API key" }, { "name": "by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "key" ] }, "description": "by=key adds a per-key breakdown to each day" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "Bad range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key and no admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/decisions": { "get": { "tags": [ "decisions" ], "summary": "List decisions, newest first, with filters and cursor pagination: a relying party's own, an org's relying parties, or any (admin)", "security": [ { "rpKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "evaluated_at \u2265 since" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "evaluated_at < until" }, { "name": "decision", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALLOW", "DENY" ] }, "description": "" }, { "name": "reason", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ReasonCode" }, "description": "" }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "" }, { "name": "grant_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/GrantId" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page" }, { "name": "rp", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org keys: one member relying party (default: all of them); admin: any" }, { "name": "key_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyId" }, "description": "only verifies made with this relying-party API key" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionList" } } } }, "400": { "description": "Bad filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No RP key, org key or admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "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." } }, "/decisions/{receipt_id}": { "get": { "tags": [ "decisions" ], "summary": "A receipt and its outcome ledger", "security": [ { "rpKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "receipt_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "rp", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org keys: one member relying party (default: all of them); admin: any" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Decision" } } } }, "401": { "description": "No RP key, org key or admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not this RP's decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/decisions/{receipt_id}/outcomes": { "post": { "tags": [ "decisions" ], "summary": "Append an Outcome Attestation (\u00a79) (the RP\u2019s own key, or its org\u2019s org:admin key with ?subject=)", "security": [ { "rpKey": [] }, { "orgKey": [] } ], "parameters": [ { "name": "receipt_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subject", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "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)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutcomeEvent" } } } }, "responses": { "201": { "description": "Recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attestation" } } } }, "400": { "description": "Unknown type or field, missing required field, bad correction_of", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not an RP key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "org:read key, or an RP key naming another subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not this RP's decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/evidence/{hash}": { "get": { "tags": [ "public" ], "summary": "Exact bytes of an artifact by hash (\u00a78)", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "sha256: or bare hex" } ], "responses": { "200": { "description": "The bytes, with their original content type and immutable cache headers", "content": { "*/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Unknown hash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/status-lists/{path}": { "get": { "tags": [ "public" ], "summary": "A Bitstring Status List credential (also served at the bare path on status.)", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string" }, "description": "/" } ], "responses": { "200": { "description": "Compact JWS (vc+jwt), Cache-Control max-age=30", "content": { "application/vc+jwt": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/did.json": { "get": { "tags": [ "public" ], "summary": "The service DID document (receipt and status-list keys)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DidDocument" } } } } } } }, "/org/{slug}/did.json": { "get": { "tags": [ "public" ], "summary": "A managed Principal's DID document", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "application/did+json", "content": { "application/did+json": { "schema": { "$ref": "#/components/schemas/DidDocument" } } } }, "404": { "description": "Unknown slug", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/demo/info": { "get": { "tags": [ "sandbox" ], "summary": "Sandbox identities, the fixed Grant limits and lifetime", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoInfo" } } } }, "404": { "description": "Sandbox disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/demo/mint": { "post": { "tags": [ "sandbox" ], "summary": "Mint a sandbox Grant and a fresh Proof for a fixed purchase", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoMintRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DemoMint" } } } }, "404": { "description": "Sandbox disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/demo/verify": { "post": { "tags": [ "sandbox" ], "summary": "POST /verify as the sandbox relying party (no key in the browser)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "Malformed envelope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sandbox disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/demo/revoke": { "post": { "tags": [ "sandbox" ], "summary": "Revoke a sandbox Grant", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeResponse" } } } }, "400": { "description": "Bad grant_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Sandbox disabled, or not a sandbox Grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs": { "post": { "tags": [ "orgs" ], "summary": "Create an organization (admin)", "security": [ { "adminToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgCreateRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Org" } } } }, "400": { "description": "Bad slug or name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slug taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org_id}": { "get": { "tags": [ "orgs" ], "summary": "The org and its members", "security": [ { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgWithMembers" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org, or a key of another subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org_id}/members": { "post": { "tags": [ "orgs" ], "summary": "Attach an existing Principal or relying party to the org (admin)", "security": [ { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMemberRequest" } } } }, "responses": { "200": { "description": "Attached (idempotent)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgMemberAdded" } } } }, "400": { "description": "Bad DID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org or subject", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Subject belongs to another org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org_id}/api-keys": { "get": { "tags": [ "orgs" ], "summary": "The org's API keys (ids only)", "security": [ { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyList" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "orgs" ], "summary": "Issue an org key with role read or admin (shown once)", "security": [ { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgApiKeyRequest" } } } }, "responses": { "201": { "description": "Issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssued" } } } }, "400": { "description": "Bad role or label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "org:read key cannot issue keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org_id}/api-keys/{key_id}/revoke": { "post": { "tags": [ "orgs" ], "summary": "Revoke an org key by its public id (immediate, idempotent)", "security": [ { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{12}$" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "org:read key cannot revoke keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org or key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkpoints/latest": { "get": { "tags": [ "transparency", "public" ], "summary": "The most recent closed day's checkpoint", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkpoint" } } } }, "404": { "description": "No day closed yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkpoints/{day}": { "get": { "tags": [ "transparency", "public" ], "summary": "The checkpoint for a UTC day (immutable once published)", "parameters": [ { "name": "day", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-15" }, "description": "UTC day" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checkpoint" } } } }, "404": { "description": "Day not closed, or not a UTC day", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkpoints/{day}/leaves": { "get": { "tags": [ "transparency", "public" ], "summary": "The day's leaf hashes, one hex SHA-256 per line in tree order; merkleRoot(leaves) equals the checkpoint root", "parameters": [ { "name": "day", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-09-15" }, "description": "UTC day" } ], "responses": { "200": { "description": "text/plain; headers X-Delegus-Tree-Size and X-Delegus-Root", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Day not closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkpoints/close": { "post": { "tags": [ "transparency" ], "summary": "Close every ended UTC day now (admin; idempotent; the maintenance loop does this every 5 minutes)", "security": [ { "adminToken": [] } ], "responses": { "200": { "description": "Days closed in this run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckpointsClosed" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/decisions/{receipt_id}/inclusion": { "get": { "tags": [ "transparency", "public" ], "summary": "Inclusion proof of a receipt id in its day's checkpoint; 202 while the day is still open", "parameters": [ { "name": "receipt_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Proof", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InclusionProof" } } } }, "202": { "description": "Day not closed yet (Retry-After: 3600)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InclusionPending" } } } }, "404": { "description": "Unknown receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/decisions/export": { "get": { "tags": [ "decisions" ], "summary": "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)", "security": [ { "rpKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "evaluated_at \u2265 since" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "evaluated_at < until" }, { "name": "decision", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALLOW", "DENY" ] }, "description": "" }, { "name": "reason", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ReasonCode" }, "description": "" }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "" }, { "name": "grant_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/GrantId" }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "next_cursor from the previous page" }, { "name": "rp", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org keys: one member relying party (default: all of them); admin: any" }, { "name": "key_id", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/ApiKeyId" }, "description": "only verifies made with this relying-party API key" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ndjson", "csv" ], "default": "ndjson" }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "description": "" } ], "responses": { "200": { "description": "Rows, newest first. Headers X-Delegus-Rows and X-Delegus-Next-Cursor (empty on the last page).", "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/DecisionExportRow" } }, "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad filter or format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No RP key, org key or admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/decisions/stats": { "get": { "tags": [ "decisions" ], "summary": "Decisions and outcomes rolled up per Principal over a range (default: last 30 days)", "security": [ { "rpKey": [] }, { "orgKey": [] }, { "adminToken": [] }, { "observerKey": [] } ], "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "inclusive; default 29 days ago 00:00Z" }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "exclusive; default tomorrow 00:00Z" }, { "name": "rp", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "org keys: one member relying party; admin: any" }, { "name": "principal", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DidWeb" }, "description": "one Principal" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionStats" } } } }, "400": { "description": "Bad range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No RP key, org key or admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/grants/{id}/consumption": { "get": { "tags": [ "principal" ], "summary": "Consumable Grants (v0.3): balances and consumption log of a Grant", "security": [ { "principalKey": [] }, { "orgKey": [] }, { "rpKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/GrantId" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "next_cursor from the previous page (a log version)" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantConsumption" } } } }, "400": { "description": "Bad cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown Grant, or a key without access (RPs see Grants they have verified)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/access/v1/evaluation": { "post": { "tags": [ "authzen" ], "summary": "AuthZEN Access Evaluation: subject/action/resource/context \u2192 decision, backed by a Delegus receipt", "security": [ { "rpKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthZenRequest" } } } }, "responses": { "200": { "description": "Decision (true only for ALLOW); context carries the Delegus reason and the receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthZenResponse" } } } }, "400": { "description": "Request does not map to a verification (no permit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not a relying-party key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "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.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (the RP's verify limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/authzen-configuration": { "get": { "tags": [ "authzen", "public" ], "summary": "AuthZEN PDP metadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthZenConfiguration" } } } } } } }, "/metrics": { "get": { "tags": [ "metrics", "public" ], "summary": "Aggregate service metrics (public, no per-subject data)", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366, "default": 30 }, "description": "verify-total window" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metrics" } } } }, "400": { "description": "Bad days", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/observer-keys": { "get": { "tags": [ "metrics" ], "summary": "List observer keys (admin)", "security": [ { "adminToken": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "metrics" ], "summary": "Issue an observer key: service-wide read of /decisions/stats and /usage only (admin; shown once)", "security": [ { "adminToken": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyRequest" } } } }, "responses": { "201": { "description": "Issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyIssued" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/observer-keys/{key_id}/revoke": { "post": { "tags": [ "metrics" ], "summary": "Revoke an observer key (admin)", "security": [ { "adminToken": [] } ], "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{12}$" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "description": "Not admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown observer key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/self-serve": { "post": { "tags": [ "onboarding" ], "security": [ { "provisionKey": [] } ], "summary": "Self-serve signup: provision an org, a managed relying party, its keys and a starter first ALLOW (console)", "description": "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": "x-delegus-client-ip", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 64 }, "description": "The end customer's IP address, forwarded by the console." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServeRequest" } } } }, "responses": { "201": { "description": "Provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServeBundle" } } } }, "400": { "description": "Bad slug, name or admin_email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or wrong provision key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Self-serve is not enabled on this deployment, or the relying party does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Slug taken or reserved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (per provision key, per customer IP, per relying party, or the daily ceiling)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/self-serve/starter": { "post": { "tags": [ "onboarding" ], "security": [ { "provisionKey": [] } ], "summary": "Mint a fresh starter Grant and Proof for a self-serve relying party", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServeRpRequest" } } } }, "responses": { "200": { "description": "A fresh starter", "content": { "application/json": { "schema": { "type": "object", "required": [ "starter" ], "properties": { "starter": { "$ref": "#/components/schemas/SelfServeStarter" } } } } } }, "400": { "description": "rp_did is not a managed relying party DID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or wrong provision key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Self-serve is not enabled on this deployment, or the relying party does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (per provision key, per customer IP, per relying party, or the daily ceiling)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/self-serve/first-receipt": { "post": { "tags": [ "onboarding" ], "security": [ { "provisionKey": [] } ], "summary": "Verify a fresh starter as the tenant's relying party and return the signed receipt", "description": "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.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelfServeRpRequest" } } } }, "responses": { "200": { "description": "The signed receipt (ALLOW for a healthy tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "description": "rp_did is not a managed relying party DID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or wrong provision key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Self-serve is not enabled on this deployment, or the relying party does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (per provision key, per customer IP, per relying party, or the daily ceiling)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conformance/runs": { "post": { "tags": [ "conformance" ], "security": [ { "rpKey": [] }, { "principalKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "summary": "Start a hosted conformance run: the published vectors against your endpoint", "description": "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}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConformanceRunRequest" } } } }, "responses": { "202": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConformanceRun" } } } }, "400": { "description": "Not an https URL, carries credentials, or is a Delegus host", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No valid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A run is already running for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/conformance/runs/{run_id}": { "get": { "tags": [ "conformance" ], "security": [ { "rpKey": [] }, { "principalKey": [] }, { "orgKey": [] }, { "adminToken": [] } ], "summary": "Read a hosted conformance run and its report", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConformanceRun" } } } }, "401": { "description": "No valid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such run for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orgs/{org_id}/entitlement": { "get": { "tags": [ "orgs" ], "summary": "Read an org's production entitlement and what the gate would decide now (console, admin)", "security": [ { "provisionKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } } ], "responses": { "200": { "description": "The stored row (null fields when none is stored) and the effective decision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } } }, "401": { "description": "Not the provision key or admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "orgs" ], "summary": "Set an org's production entitlement: allowed or blocked, until when, and a check cap (console, admin)", "description": "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.", "security": [ { "provisionKey": [] }, { "adminToken": [] } ], "parameters": [ { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^org_[0-7][0-9A-HJKMNP-TV-Z]{25}$", "example": "org_01K4Q7ZP9X2M3N4R5S6T7V8W9Y" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitlementRequest" } } } }, "responses": { "200": { "description": "Stored (applied true) or ignored as older than the stored row (applied false); the row now in effect", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entitlement" } } } }, "400": { "description": "Invalid body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Not the provision key or admin", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown org", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }