# Generated by scripts/generate-openapi.ts { "openapi": "3.1.0", "info": { "title": "@dlbr/id Verification Gateway API", "version": "0.1.0", "description": "B2B digital identity and age verification gateway using OID4VP, SD-JWT-VC, and ISO/IEC 18013-5 mDOC." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://{host}", "variables": { "host": { "default": "gateway.example.com" } } } ], "tags": [ { "name": "Sessions", "description": "Tenant-scoped verification sessions" }, { "name": "OID4VP", "description": "Wallet-facing OID4VP request and response endpoints" }, { "name": "Webhooks", "description": "Signed webhook endpoint and failure management" }, { "name": "API keys", "description": "Tenant API-key lifecycle" }, { "name": "Audit", "description": "Tenant-scoped audit records" }, { "name": "Admin", "description": "Server-to-server aggregate metrics" }, { "name": "Discovery", "description": "Public DID and JWK discovery" } ], "paths": { "/v1/sessions": { "post": { "tags": [ "Sessions" ], "summary": "Create a verification session", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } } }, "responses": { "201": { "description": "Session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "400": { "description": "Invalid session request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Cloudflare Durable Object session ID" } } ], "get": { "tags": [ "Sessions" ], "summary": "Read session status", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatus" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Sessions" ], "summary": "Purge a session", "security": [ { "bearerApiKey": [] } ], "responses": { "204": { "description": "Session purged" }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{sessionId}/ws": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Cloudflare Durable Object session ID" } } ], "get": { "tags": [ "Sessions" ], "summary": "Open a session status WebSocket", "description": "Upgrade the request to a WebSocket. Requires the session:read scope. SDK clients authenticate with the dlbr-id-v1 subprotocol and API key, and receive replayable status events with sequence numbers.", "security": [ { "bearerApiKey": [] } ], "responses": { "101": { "description": "WebSocket protocol switch" }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sessions/{sessionId}/open": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Cloudflare Durable Object session ID" } }, { "name": "scheme", "in": "query", "schema": { "type": "string", "enum": [ "openid4vp", "eudi-wallet", "haip" ], "default": "openid4vp" } } ], "get": { "tags": [ "Sessions" ], "summary": "Open the wallet deep link", "security": [], "responses": { "302": { "description": "Redirect to the selected wallet URI" }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oid4vp/request/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Cloudflare Durable Object session ID" } } ], "get": { "tags": [ "OID4VP" ], "summary": "Fetch a signed Request Object", "description": "Public wallet endpoint used by the jar profile.", "security": [], "responses": { "200": { "description": "application/oauth-authz-req+jwt", "content": { "application/oauth-authz-req+jwt": { "schema": { "type": "string" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oid4vp/response/{sessionId}": { "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Cloudflare Durable Object session ID" } } ], "post": { "tags": [ "OID4VP" ], "summary": "Receive a wallet presentation", "description": "Public wallet callback. Accepts JSON or application/x-www-form-urlencoded direct_post; jar responses may carry an encrypted response field.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationResponse" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "vp_token", "state", "presentation_submission" ], "properties": { "vp_token": { "type": "string" }, "state": { "type": "string" }, "presentation_submission": { "type": "string" } } } } } }, "responses": { "200": { "description": "Presentation accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" } } } } } }, "400": { "description": "Presentation rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Session is no longer pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Discovery" ], "summary": "Get verifier public keys", "security": [], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JWKSet" } } } } } } }, "/.well-known/did.json": { "get": { "tags": [ "Discovery" ], "summary": "Get verifier DID document", "security": [], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/webhook-endpoint": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook endpoint metadata", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Webhooks" ], "summary": "Create or replace webhook endpoint", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointSecret" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/failures": { "get": { "tags": [ "Webhooks" ], "summary": "List dead-lettered webhook deliveries", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "properties": { "failures": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookFailure" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid pagination cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhooks/failures/{failureId}/retry": { "parameters": [ { "name": "failureId", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "Webhooks" ], "summary": "Replay a failed webhook", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "REPLAYED" }, "id": { "type": "string" }, "session_id": { "type": "string" } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/audit-log": { "get": { "tags": [ "Audit" ], "summary": "List tenant audit entries", "security": [ { "bearerApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Invalid pagination cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys": { "get": { "tags": [ "API keys" ], "summary": "List tenant API keys", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_keys": { "type": "array", "items": { "$ref": "#/components/schemas/APIKey" } } } } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "API keys" ], "summary": "Create a scoped API key", "security": [ { "bearerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAPIKeyRequest" } } } }, "responses": { "201": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeySecret" } } } }, "400": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "delete": { "tags": [ "API keys" ], "summary": "Revoke an API key", "security": [ { "bearerApiKey": [] } ], "responses": { "204": { "description": "Key revoked" }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "post": { "tags": [ "API keys" ], "summary": "Rotate an API key", "security": [ { "bearerApiKey": [] } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIKeySecret" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/admin/metrics": { "get": { "tags": [ "Admin" ], "summary": "Read aggregate verification metrics", "security": [ { "adminBearer": [] } ], "parameters": [ { "name": "window_hours", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 720, "default": 24 } } ], "responses": { "200": { "description": "JSON response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsSummary" } } } }, "401": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Error response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "API key" }, "adminBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "Admin API token" } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "CreateSessionRequest": { "oneOf": [ { "$ref": "#/components/schemas/LegacySessionRequest" }, { "$ref": "#/components/schemas/CustomSessionRequest" } ] }, "LegacySessionRequest": { "type": "object", "required": [ "issuer_id" ], "properties": { "ttl_ms": { "type": "integer", "minimum": 60000, "maximum": 86400000 }, "issuer_id": { "type": "string" }, "format": { "type": "string", "enum": [ "vc+sd-jwt", "mso_mdoc" ] }, "redirect_uri": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "CustomSessionRequest": { "type": "object", "required": [ "credentials" ], "properties": { "ttl_ms": { "type": "integer", "minimum": 60000, "maximum": 86400000 }, "credentials": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/CredentialRequest" } }, "same_subject_groups": { "type": "array", "items": { "type": "array", "minItems": 2, "items": { "type": "string" } } }, "redirect_uri": { "type": "string" } }, "additionalProperties": false }, "CredentialRequest": { "type": "object", "required": [ "format", "issuer_id", "claims" ], "properties": { "id": { "type": "string" }, "format": { "type": "string", "enum": [ "vc+sd-jwt", "mso_mdoc" ] }, "issuer_id": { "type": "string" }, "namespace": { "type": "string" }, "doc_type": { "type": "string" }, "claims": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^[A-Za-z0-9_]+$" } }, "alg": { "type": "string", "enum": [ "ES256", "ES384", "ES512" ] }, "subject_claim_paths": { "type": "array", "items": { "type": "string" } }, "claim_filters": { "type": "object", "additionalProperties": { "type": "object" } } }, "additionalProperties": false }, "CreateSessionResponse": { "type": "object", "required": [ "session_id", "livemode", "expires_at", "qr_code_url", "deep_links" ], "properties": { "session_id": { "type": "string" }, "livemode": { "type": "boolean", "description": "Whether this session targets live data. False means sandbox/test data." }, "expires_at": { "type": "string", "format": "date-time" }, "qr_code_url": { "type": "string" }, "deep_links": { "type": "object", "additionalProperties": { "type": "string" } } } }, "SessionStatus": { "type": "object", "required": [ "session_id", "status", "livemode" ], "properties": { "session_id": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATED", "PENDING", "VERIFYING", "VERIFIED", "FAILED", "EXPIRED" ] }, "livemode": { "type": "boolean", "description": "Whether this session targets live data. False means sandbox/test data." }, "expires_at": { "type": "string", "format": "date-time" }, "claims": { "type": "object" }, "reason": { "type": "string" }, "verification_details": { "type": "object" } } }, "AuthorizationResponse": { "type": "object", "required": [ "vp_token", "state", "presentation_submission" ], "properties": { "vp_token": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "state": { "type": "string" }, "presentation_submission": { "type": "object" } } }, "JWKSet": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object" } } } }, "WebhookEndpoint": { "type": "object", "required": [ "client_id", "url", "created_at", "host_status" ], "properties": { "client_id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "created_at": { "type": "string" }, "host_status": { "type": "string", "enum": [ "PENDING", "APPROVED", "REJECTED" ], "description": "Operator review status of the endpoint's hostname. Delivery only reaches APPROVED hosts." }, "host_review_note": { "type": [ "string", "null" ], "description": "Operator-provided reason, set when host_status is REJECTED." } } }, "WebhookEndpointSecret": { "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "required": [ "signing_secret" ], "properties": { "signing_secret": { "type": "string", "writeOnly": true } } } ] }, "PutWebhookEndpointRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "signing_secret": { "type": "string", "minLength": 16, "writeOnly": true } }, "additionalProperties": false }, "WebhookFailure": { "type": "object", "properties": { "id": { "type": "string" }, "session_id": { "type": "string" }, "client_id": { "type": "string" }, "payload": { "type": "object" }, "error_message": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "failed_at": { "type": "string" } } }, "APIKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } }, "revoked": { "type": "boolean" }, "livemode": { "type": "boolean", "description": "Whether this key targets live data. False means sandbox/test data." }, "created_at": { "type": "string" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Absolute UTC expiry. Null means the key does not expire." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Most recent successful authentication. Null means the key has not been used." } } }, "APIKeySecret": { "type": "object", "required": [ "id", "api_key", "livemode", "expires_at", "last_used_at" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "api_key": { "type": "string", "writeOnly": true }, "livemode": { "type": "boolean", "description": "Whether this key targets live data. False means sandbox/test data." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Absolute UTC expiry. Null means the key does not expire." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Most recent successful authentication. Null means the key has not been used." } } }, "CreateAPIKeyRequest": { "type": "object", "required": [ "scopes" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "scopes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "session:create", "session:read", "audit:read", "api_keys:manage" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Future absolute UTC expiry. Omit or use null for a non-expiring key." } }, "additionalProperties": false }, "AuditEntry": { "type": "object", "properties": { "session_id": { "type": "string" }, "status": { "type": "string" }, "credential_types": { "type": "array", "items": { "type": "string" } }, "issuer_ids": { "type": "array", "items": { "type": "string" } }, "error_code": { "type": "string" }, "latency_ms": { "type": "integer" }, "occurred_at": { "type": "string" }, "prev_hash": { "type": "string" }, "entry_hash": { "type": "string" }, "chain_intact": { "type": "boolean" } } }, "MetricsSummary": { "type": "object", "properties": { "window_hours": { "type": "integer" }, "total_estimated": { "type": "number" }, "verified_estimated": { "type": "number" }, "failed_estimated": { "type": "number" }, "success_rate": { "type": "number" }, "latency_ms_p50": { "type": "number", "nullable": true, "description": "End-to-end session latency, session creation through verification completion." }, "latency_ms_p95": { "type": "number", "nullable": true, "description": "End-to-end session latency, session creation through verification completion." }, "processing_latency_ms_p50": { "type": "number", "nullable": true, "description": "Backend verification processing time, excluding wallet/user time and post-verification delivery." }, "processing_latency_ms_p95": { "type": "number", "nullable": true, "description": "Backend verification processing time, excluding wallet/user time and post-verification delivery." }, "by_credential_type": { "type": "array" }, "by_error_code": { "type": "array" } } } } } }