{ "openapi": "3.1.0", "info": { "title": "AuthHub NHS ReBAC Authorization & Governance API", "version": "1.0.0", "description": "Production REST, AuthZEN, SCIM 2.0, and Zanzibar ReBAC Authorization Platform for NHS Clinical and Enterprise AI Systems.", "termsOfService": "https://fga.authhub.cloud/register/terms", "contact": { "name": "AuthHub Platform Engineering", "url": "https://fga.authhub.cloud/docs", "email": "support@authhub.cloud" }, "license": { "name": "Proprietary / NHS Digital Framework", "url": "https://fga.authhub.cloud/register/terms" } }, "servers": [ { "url": "https://fga.authhub.cloud", "description": "Production Global Ingress Gateway" }, { "url": "http://localhost:3000", "description": "Local Developer Daemon Gateway" } ], "tags": [ { "name": "Group 1: ReBAC Core", "description": "SpiceDB Google Zanzibar relationship-based access control and REST alternatives" }, { "name": "Group 2: AuthZEN SARC", "description": "OpenID AuthZEN SARC evaluation, batch decisions, and reverse search" }, { "name": "Group 3: Lifecycle & SCIM", "description": "RFC 7644 SCIM 2.0 directory ingestion, connection administration, and deprovisioning guard" }, { "name": "Group 4: Workload Identity", "description": "RFC 8693 token exchange, introspection, and trust domain issuers" }, { "name": "Group 5: Analytics & Telemetry", "description": "Real-time authorization telemetry, latency percentiles, error heatmaps, and audit exports" }, { "name": "Group 6: AI Agent Registry", "description": "Registration, credential management, MCP tool authorization, and service identities" }, { "name": "Group 7: COAZ Mappings", "description": "Context-aware authorization JSONPath transformations and simulation engine" }, { "name": "Group 8: Webhooks & DLQ", "description": "HMAC-SHA256 event streams, delivery retries, and dead-letter queue replay" }, { "name": "Group 9: Break-Glass REST", "description": "Emergency medical access escalation, Caldicott justification, and RFC 3161 audit verification" }, { "name": "Group 10: Policy Administration", "description": "Schema AST definition parsing, per-object-type CRUD, and version rollback" }, { "name": "Group 11: OIDC Discovery", "description": "OpenID configuration, RFC 8414 server metadata, RFC 9728 protected resource metadata, and JWKS" }, { "name": "Group 12: HSM & BYOK", "description": "FIPS 140-2 Level 3 hardware security module attestation, rotation, and envelope wrapping" }, { "name": "Group 13: CIMD & Billing", "description": "Client-ID-Metadata validation policies, plan quotas, and Stripe billing lifecycle" }, { "name": "Group 14: Health & Diagnostics", "description": "Multi-system liveness/readiness probes, Prometheus metrics, and operator auth" }, { "name": "Specialist: NHI Management", "description": "Non-human identity state machine, machine credentials, and automated self-repair" }, { "name": "Specialist: Governance Signals", "description": "Multi-clock risk scoring, clinical registry freezes, and automated policy overrides" }, { "name": "Specialist: Autonomous Governance", "description": "Real-time policy invariants, compliance boundaries, and auto-quarantine actions" }, { "name": "Specialist: Continuous Testing", "description": "5-tier continuous automated contract, scenario, and invariant test harnesses" }, { "name": "Specialist: Database Access Gateways", "description": "Enterprise cloud database registration, ReBAC query proxying, in-flight PII masking, and kill switch controls" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Tenant or administrative Bearer JWT token" }, "TenantIdHeader": { "type": "apiKey", "in": "header", "name": "X-Tenant-ID", "description": "Primary tenant identifier UUID" }, "SubTenantIdHeader": { "type": "apiKey", "in": "header", "name": "X-Sub-Tenant-ID", "description": "Sub-tenant namespace isolation identifier" }, "UserIdentityHeader": { "type": "apiKey", "in": "header", "name": "X-User-Identity", "description": "Identity of the human or agent caller executing the operation" }, "DPoPProofHeader": { "type": "apiKey", "in": "header", "name": "DPoP", "description": "RFC 9449 Demonstrating Proof-of-Possession asymmetric JWT signature" } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable error description or error code" }, "details": { "type": "string", "description": "Underlying diagnostic context or validation issues" }, "code": { "type": "string", "description": "Standard machine-readable error token" } } }, "PermissionCheckRequest": { "type": "object", "required": [ "subjectType", "subjectId", "permission", "resourceType", "resourceId" ], "properties": { "subjectType": { "type": "string", "example": "user" }, "subjectId": { "type": "string", "example": "dr-smith" }, "permission": { "type": "string", "example": "view_record" }, "resourceType": { "type": "string", "example": "patient" }, "resourceId": { "type": "string", "example": "patient-123" } } }, "PermissionCheckResponse": { "type": "object", "required": [ "allowed", "checkedAt" ], "properties": { "allowed": { "type": "boolean", "example": true }, "checkedAt": { "type": "string", "format": "date-time" }, "latencyMs": { "type": "number", "example": 3 }, "governance": { "type": "boolean", "example": false }, "reason": { "type": "string", "example": "GOVERNANCE_SUSPENSION" }, "suspensionId": { "type": "string", "example": "susp_01HYX..." } } }, "TupleWriteRequest": { "type": "object", "required": [ "objectType", "objectId", "relation", "subjectType", "subjectId" ], "properties": { "objectType": { "type": "string", "example": "patient" }, "objectId": { "type": "string", "example": "patient-123" }, "relation": { "type": "string", "example": "treating_clinician" }, "subjectType": { "type": "string", "example": "user" }, "subjectId": { "type": "string", "example": "dr-smith" } } }, "TupleWriteResponse": { "type": "object", "properties": { "objectType": { "type": "string" }, "objectId": { "type": "string" }, "relation": { "type": "string" }, "subjectType": { "type": "string" }, "subjectId": { "type": "string" }, "zetaToken": { "type": "string", "example": "GhUKEzE3MTk4NTcxODkyMzg1NTE4MjEYASAB" }, "createdAt": { "type": "string", "format": "date-time" } } }, "AuthZenEvaluationRequest": { "type": "object", "required": [ "subject", "action", "resource" ], "properties": { "subject": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "action": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "resource": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "context": { "type": "object" } } }, "AuthZenEvaluationResponse": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "boolean" }, "context": { "type": "object", "properties": { "reason": { "type": "array", "items": { "type": "object" } }, "obligations": { "type": "array", "items": { "type": "object" } } } } } }, "BreakGlassFulfillmentRequest": { "type": "object", "required": [ "event_id", "justification", "authorising_clinician", "duration_seconds" ], "properties": { "event_id": { "type": "string", "format": "uuid" }, "justification": { "type": "string" }, "authorising_clinician": { "type": "string", "format": "email" }, "duration_seconds": { "type": "integer", "default": 1800 } } }, "DatabaseConnectionRegistrationRequest": { "type": "object", "required": [ "name", "database_type", "host", "port", "database", "user", "password" ], "properties": { "name": { "type": "string", "example": "aiven-market-data-prod" }, "database_type": { "type": "string", "enum": [ "postgres", "mysql", "cockroach" ], "example": "postgres" }, "host": { "type": "string", "example": "pg-authhub1-authhub-poc1.f.aivencloud.com" }, "port": { "type": "integer", "example": 10952 }, "database": { "type": "string", "example": "defaultdb" }, "user": { "type": "string", "example": "avnadmin" }, "password": { "type": "string", "writeOnly": true, "example": "••••••••••••" }, "ssl": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "require", "disable" ] } ], "example": "require" }, "governance": { "type": "object", "properties": { "technical_owner": { "type": "string", "example": "Hanif@NiloDevelopments.onmicrosoft.com" }, "business_owner": { "type": "string", "example": "aaron.barlow@authhub.cloud" }, "deputies": { "type": "array", "items": { "type": "string" }, "example": [ "abby.nguyen@authhub.cloud", "adam.atkins@authhub.cloud" ] }, "escalation_contact": { "type": "string", "example": "Hanif@NiloDevelopments.onmicrosoft.com" } } }, "security_controls": { "type": "object", "properties": { "max_rows_per_query": { "type": "integer", "example": 50 }, "prohibited_keywords": { "type": "array", "items": { "type": "string" }, "example": [ "DROP", "TRUNCATE", "ALTER", "DELETE" ] }, "pii_masking": { "type": "boolean", "example": true }, "require_where_clause": { "type": "boolean", "example": true } } } } }, "DatabaseConnectionResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "8f700688-46fb-40a2-a05e-a6119f6f6004" }, "name": { "type": "string", "example": "aiven-market-data-prod" }, "database_type": { "type": "string", "example": "postgres" }, "host": { "type": "string", "example": "pg-authhub1-authhub-poc1.f.aivencloud.com" }, "port": { "type": "integer", "example": 10952 }, "database": { "type": "string", "example": "defaultdb" }, "user": { "type": "string", "example": "avnadmin" }, "ssl": { "type": "string", "example": "require" }, "assigned_gateway_url": { "type": "string", "example": "https://api.authhub.cloud/api/v1/tenant/database-connections/8f700688-46fb-40a2-a05e-a6119f6f6004/query" }, "governance": { "type": "object" }, "security_controls": { "type": "object" }, "discovered_tables": { "type": "array", "items": { "type": "string" }, "example": [ "market_data.trade_executions", "market_data.portfolio_summary" ] }, "created_at": { "type": "string", "format": "date-time" } } } } }, "DatabaseQueryRequest": { "type": "object", "required": [ "sql", "agent_id", "user_id" ], "properties": { "sql": { "type": "string", "example": "SELECT trade_id, trader_account, symbol, execution_price FROM market_data.trade_executions" }, "agent_id": { "type": "string", "example": "nhi-market-analyst-agent-01" }, "user_id": { "type": "string", "example": "Hanif@NiloDevelopments.onmicrosoft.com" }, "action": { "type": "string", "default": "query", "example": "query" } } }, "DatabaseQueryResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "connection_id": { "type": "string", "format": "uuid" }, "rows": { "type": "array", "items": { "type": "object" } }, "row_count": { "type": "integer", "example": 10 }, "authz_evaluation": { "type": "object", "properties": { "decision": { "type": "string", "example": "ALLOW" }, "agent_id": { "type": "string" }, "user_id": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "security": { "type": "object", "properties": { "pii_masked": { "type": "boolean", "example": true }, "masked_fields": { "type": "array", "items": { "type": "string" }, "example": [ "trader_account" ] }, "execution_time_ms": { "type": "number", "example": 42 } } } } }, "DatabaseKillSwitchRequest": { "type": "object", "required": [ "active" ], "properties": { "active": { "type": "boolean", "example": true }, "reason": { "type": "string", "example": "High-frequency extraction anomaly detected" }, "operator_id": { "type": "string", "example": "Hanif@NiloDevelopments.onmicrosoft.com" } } }, "DatabaseKillSwitchResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "connection_id": { "type": "string", "format": "uuid" }, "kill_switch": { "type": "object", "properties": { "active": { "type": "boolean", "example": true }, "activated_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" }, "operator_id": { "type": "string" } } } } } } }, "paths": { "/api/v1/tenant/permissions/check": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Check Permission (REST)", "description": "Direct REST equivalent to gRPC CheckPermission. Evaluates governance suspensions and break-glass overrides.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionCheckRequest" } } } }, "responses": { "200": { "description": "Authorization check completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionCheckResponse" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/tenant/permissions/expand": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Expand Permission Tree", "description": "Expands the full relationship graph tree explaining authorization decisions.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Expanded graph tree" } } } }, "/api/v1/tenant/tuples": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Query Tuples (REST)", "description": "Read relationship tuples matching namespace, resource, or subject filters.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Paginated list of relationship tuples" } } }, "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Write Tuple (REST)", "description": "Write single relationship tuple with TOUCH semantics.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TupleWriteRequest" } } } }, "responses": { "201": { "description": "Tuple created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TupleWriteResponse" } } } } } }, "delete": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Delete Tuple (REST)", "description": "Delete relationship tuple from SpiceDB.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tuple deleted" } } } }, "/api/v1/tenant/schema": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Read Active Schema", "description": "Fetches active schema DSL text and current zeta_token.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current schema definition" } } }, "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Deploy Schema", "description": "Deploys a new schema text string to the isolated tenant namespace.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema deployed with new zeta_token" } } } }, "/api/v1/tenant/schema/templates": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "List Vertical ReBAC Schema Templates", "description": "Retrieves pre-packaged, production-tested Zanzibar authorization schemas for Healthcare (NHS Caldicott/emergency override models) and Enterprise B2B SaaS (hierarchical RBAC-to-ReBAC tenancy models).", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Catalog of vertical schema templates" } } } }, "/api/v1/tenant/schema/dry-run": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Dry-Run Schema Validation", "description": "Validates schema candidate without applying changes, returning structural diff.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema diff and safety validation" } } } }, "/api/v1/tenant/schemas/diff": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Compare Schema Versions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Structural diff between versions" } } } }, "/api/v1/tenant/schemas/versions/create": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Create Schema Version Draft", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Draft version created" } } } }, "/api/v1/tenant/schemas/versions/list": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "List Schema Versions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of schema versions" } } } }, "/api/v1/tenant/schemas/versions/rollback": { "post": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Rollback Schema Version", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Rolled back to prior schema version" } } } }, "/api/v1/tenant/audit": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Get Admin Audit Trail", "description": "Paginated admin audit trail with filtering by operationType and actor.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 20 } }, { "name": "operationType", "in": "query", "schema": { "type": "string" } }, { "name": "actor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated audit records" } } } }, "/api/v1/tenant/audit/verify-chain": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Verify Merkle Hash Chain", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Chain validation result" } } } }, "/api/v1/tenant/audit/graph-at": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Reconstruct Graph At Timestamp", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Historical graph topology" } } } }, "/api/v1/tenant/audit/permission-at": { "get": { "tags": [ "Group 1: ReBAC Core" ], "summary": "Permission Check At Timestamp", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Historical permission check result" } } } }, "/authzen/v1/evaluation": { "post": { "tags": [ "Group 2: AuthZEN SARC" ], "summary": "Evaluate Single Access Request", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthZenEvaluationRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthZenEvaluationResponse" } } } } } } }, "/authzen/v1/evaluations": { "post": { "tags": [ "Group 2: AuthZEN SARC" ], "summary": "Batch Access Request Evaluations", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Batch decision list" } } } }, "/authzen/v1/resource-search": { "post": { "tags": [ "Group 2: AuthZEN SARC" ], "summary": "Resource Search (Reverse Lookup)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Permitted resources list" } } } }, "/authzen/v1/subject-search": { "post": { "tags": [ "Group 2: AuthZEN SARC" ], "summary": "Subject Search (Reverse Lookup)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Permitted subjects list" } } } }, "/authzen/v1/action-search": { "post": { "tags": [ "Group 2: AuthZEN SARC" ], "summary": "Action Search", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Permitted actions list" } } } }, "/api/v1/tenant/authzen-audit": { "get": { "tags": [ "Group 2: AuthZEN SARC" ], "summary": "Query AuthZEN Audit Records", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Historical AuthZEN decisions" } } } }, "/scim/v2/{connectionId}/Users": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List & Filter Users", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SCIM ListResponse" } } }, "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Provision User", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created SCIM User" } } } }, "/scim/v2/{connectionId}/Users/{userId}": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Get SCIM User", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SCIM User" } } }, "patch": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Patch SCIM User", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Updated SCIM User" } } }, "delete": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Deprovision SCIM User", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Soft deleted" }, "204": { "description": "Hard deleted" } } } }, "/scim/v2/{connectionId}/Groups": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List SCIM Groups", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SCIM Group List" } } }, "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Create SCIM Group", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created SCIM Group" } } } }, "/scim/v2/{connectionId}/Groups/{groupId}": { "patch": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Update SCIM Group Membership", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Updated SCIM Group" } } }, "delete": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Delete SCIM Group", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Deleted SCIM Group" } } } }, "/api/v1/tenant/scim/connections": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List SCIM Connections", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of configured connections" } } }, "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Create SCIM Connection", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created connection with bearer token" } } } }, "/api/v1/tenant/scim/connections/{connectionId}": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Inspect SCIM Connection", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Connection details" } } }, "delete": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Decommission SCIM Connection", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Connection soft-deleted" } } } }, "/api/v1/tenant/scim/connections/{connectionId}/pause": { "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Pause SCIM Connection", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Connection paused" } } } }, "/api/v1/tenant/scim/connections/{connectionId}/resume": { "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Resume SCIM Connection", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Connection resumed" } } } }, "/api/v1/tenant/scim/connections/{connectionId}/rotate-token": { "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Rotate SCIM Inbound Token", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Token rotated with grace period" } } } }, "/api/v1/tenant/scim/connections/{connectionId}/mappings": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Inspect SCIM Mapping Rules", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Ordered mapping rules" } } } }, "/api/v1/tenant/scim/connections/{connectionId}/log": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "SCIM Historical Sync Log", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Paginated synchronization events" } } } }, "/api/v1/tenant/scim/connections/{connectionId}/held-events": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List Quarantined Deprovisioning Events", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Quarantined event queue" } } }, "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Approve or Discard Held Events", "security": [ { "BearerAuth": [] }, { "UserIdentityHeader": [] } ], "responses": { "200": { "description": "Decision processed" } } } }, "/api/v1/tenant/scim/dashboard": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "SCIM Sync Telemetry Dashboard", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Aggregate sync statistics" } } } }, "/api/v1/tenant/usage": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Get Tenant Resource Consumption", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Usage and plan quotas snapshot" } } } }, "/api/v1/tenant/users": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List Synchronized Tenant Users", "description": "Query synchronized SCIM users across connections for the authenticated tenant with pagination and text search filtering.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "filter", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated user list with connection metadata" } } } }, "/api/v1/tenant/groups": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List Synchronized Tenant Groups", "description": "Query synchronized SCIM groups across connections with pagination and display name search.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "filter", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated group list with connection metadata" } } } }, "/api/v1/scim/{connectionId}/Users": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List & Filter Users (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SCIM ListResponse" } } }, "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Provision User (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created SCIM User" } } } }, "/api/v1/scim/{connectionId}/Users/{userId}": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Get SCIM User (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SCIM User" } } }, "patch": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Patch SCIM User (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Updated SCIM User" } } }, "delete": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Deprovision SCIM User (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Soft deleted" }, "204": { "description": "Hard deleted" } } } }, "/api/v1/scim/{connectionId}/Groups": { "get": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "List SCIM Groups (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "SCIM Group List" } } }, "post": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Create SCIM Group (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Created SCIM Group" } } } }, "/api/v1/scim/{connectionId}/Groups/{groupId}": { "patch": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Update SCIM Group Membership (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Updated SCIM Group" } } }, "delete": { "tags": [ "Group 3: Lifecycle & SCIM" ], "summary": "Delete SCIM Group (Canonical Prefix)", "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "Deleted SCIM Group" } } } }, "/oauth/authorize": { "get": { "tags": [ "Group 4: Workload Identity" ], "summary": "OAuth 2.0 Authorization Endpoint", "description": "Interactive authorization endpoint supporting RFC 7636 PKCE (S256). Redirects authenticated browser/agent sessions with auth code or renders IdP federation guidance.", "responses": { "200": { "description": "Federation guidance page" }, "302": { "description": "Redirect to client callback URL with code and state" } } } }, "/oauth/token": { "post": { "tags": [ "Group 4: Workload Identity" ], "summary": "RFC 8693 Token Exchange", "description": "Exchange external OIDC/SAML subject tokens for fine-grained AuthHub access tokens.", "responses": { "200": { "description": "Exchanged access token" } } } }, "/oauth/introspect": { "post": { "tags": [ "Group 4: Workload Identity" ], "summary": "RFC 7662 Token Introspection", "responses": { "200": { "description": "Token active state and claims" } } } }, "/oauth/revoke": { "post": { "tags": [ "Group 4: Workload Identity" ], "summary": "RFC 7009 Token Revocation", "responses": { "200": { "description": "Token revoked" } } } }, "/api/v1/tenants/{id}/issuers": { "get": { "tags": [ "Group 4: Workload Identity" ], "summary": "List Trusted Identity Providers", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Configured OIDC issuers" } } }, "post": { "tags": [ "Group 4: Workload Identity" ], "summary": "Register Trusted Identity Provider", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Issuer registered" } } } }, "/api/v1/tenants/{id}/workload-identities": { "get": { "tags": [ "Group 4: Workload Identity" ], "summary": "List Workload Identities", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Configured workload identities" } } }, "post": { "tags": [ "Group 4: Workload Identity" ], "summary": "Create Workload Identity Pool Binding", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Workload identity bound" } } } }, "/api/v1/tenant/analytics/overview": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Overview Summary Metrics", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "24-hour evaluation totals and health rates" } } } }, "/api/v1/tenant/analytics/evaluations": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Time-Series Evaluations", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Evaluation time-series data" } } } }, "/api/v1/tenant/analytics/latency": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Latency Percentiles (p50, p90, p99)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Rolling latency percentiles" } } } }, "/api/v1/tenant/analytics/errors": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Error Rate & Failure Codes", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Error breakdown" } } } }, "/api/v1/tenant/analytics/rollups/agents": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Agent Authorization Rollup", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent evaluation totals" } } } }, "/api/v1/tenant/analytics/rollups/break-glass": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Break-Glass Emergency Access Rollup", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Break-glass frequency metrics" } } } }, "/api/v1/tenant/analytics/rollups/tuples": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Tuple Mutation Rollup", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tuple write/delete velocity" } } } }, "/api/v1/tenant/analytics/rollups/schema": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Schema Version Rollup", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema change telemetry" } } } }, "/api/v1/tenant/analytics/rollups/scim": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "SCIM Ingress Rollup", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Sync velocity" } } } }, "/api/v1/tenant/analytics/heatmap": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Hourly Traffic Heatmap Matrix", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Day-of-week by hour load distribution" } } } }, "/api/v1/tenant/analytics/trends": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Rolling Trendlines", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Comparative period trendlines" } } } }, "/api/v1/tenant/analytics/top-resources": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Most Accessed Resources", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "High-frequency resources list" } } } }, "/api/v1/tenant/analytics/top-subjects": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Most Active Callers / Subjects", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Top subject access counts" } } } }, "/api/v1/tenant/analytics/last-used": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Stale Permission & Tuple Detector", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Unused permissions report" } } } }, "/api/v1/tenant/analytics/export": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Export Analytics CSV", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "CSV stream" } } } }, "/api/v1/tenant/analytics/leaderboard": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Authorization Activity Leaderboard", "description": "Top clinicians, agents, and callers ranked by check volume and decision rate over the given time window.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Ranked caller leaderboard" } } } }, "/api/v1/tenant/analytics/agents": { "get": { "tags": [ "Group 5: Analytics & Telemetry" ], "summary": "Agent Authorization Rollup", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Agent evaluation totals" } } } }, "/api/v1/tenant/analytics/scim": { "get": { "tags": [ "Group 3: Lifecycle & SCIM", "Group 5: Analytics & Telemetry" ], "summary": "SCIM Ingress Rollup", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Sync velocity" } } } }, "/api/v1/tenant/analytics/tuples": { "get": { "tags": [ "Group 1: ReBAC Core", "Group 5: Analytics & Telemetry" ], "summary": "Tuple Mutation Rollup", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Tuple write/delete velocity" } } } }, "/api/v1/tenant/analytics/schema": { "get": { "tags": [ "Group 1: ReBAC Core", "Group 5: Analytics & Telemetry" ], "summary": "Schema Version Rollup", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Schema change telemetry" } } } }, "/api/v1/tenant/analytics/break-glass": { "get": { "tags": [ "Group 9: Break-Glass REST", "Group 5: Analytics & Telemetry" ], "summary": "Break-Glass Emergency Access Rollup", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Break-glass frequency metrics" } } } }, "/mcp": { "post": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Model Context Protocol (MCP) Edge Gateway", "description": "Protected MCP JSON-RPC 2.0 gateway endpoint. Supports MCP spec versions 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. Handles stateless server/discover capability discovery, RFC 9728 401 challenges with resource_metadata pointer, and inline AuthZEN SARC policy evaluations (<5ms) on tools/call.", "responses": { "200": { "description": "JSON-RPC 2.0 response (server/discover, initialize, tools/list, tools/call)" }, "401": { "description": "Unauthorized — emits RFC 9728 WWW-Authenticate header with resource_metadata pointer" } } } }, "/api/v1/tenant/agent-registry": { "get": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "List Registered AI Agents", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent registry catalog" } } }, "post": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Register Autonomous AI Agent", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Agent registered with credentials" } } } }, "/api/v1/tenant/agent-registry/{id}": { "get": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Get Agent Identity Details", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent profile" } } }, "put": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Update Agent Configuration", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent updated" } } }, "delete": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Deregister AI Agent", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Agent revoked" } } } }, "/api/v1/tenant/agent-registry/{id}/verify": { "post": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Verify Agent Public Key / Attestation", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Attestation valid" } } } }, "/api/v1/tenant/agent-registry/{id}/rotate-secret": { "post": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Rotate Agent Secret", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Secret rotated" } } } }, "/api/v1/tenant/discovery/{id}": { "get": { "tags": [ "Group 6: AI Agent Registry" ], "summary": "Discover Agent Capabilities & Tools", "description": "Dynamic MCP tool discovery, agent endpoint resolution, and schema introspection.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Agent capabilities and tool manifests" } } } }, "/api/v1/tenant/coaz-mappings": { "get": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "List COAZ Mappings", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Configured JSONPath mappings" } } }, "post": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "Create COAZ Mapping", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Mapping created" } } } }, "/api/v1/tenant/coaz-mappings/{id}": { "get": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "Get COAZ Mapping", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Mapping detail" } } }, "put": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "Update COAZ Mapping", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Mapping updated" } } }, "delete": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "Delete COAZ Mapping", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Mapping deleted" } } } }, "/api/v1/tenant/coaz-mappings/{id}/versions": { "get": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "List Mapping Version History", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Historical mapping versions" } } } }, "/api/v1/tenant/coaz-mappings/simulate": { "post": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "Simulate COAZ Mapping against Payload", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Extracted context resolution preview" } } } }, "/api/v1/tenant/coaz-mappings/{id}/activate": { "post": { "tags": [ "Group 7: COAZ Mappings" ], "summary": "Activate COAZ Mapping Version", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active version updated" } } } }, "/api/v1/tenant/webhooks": { "get": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "List Webhook Subscriptions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active webhook configurations" } } }, "post": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "Create Webhook Subscription", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Webhook registered with HMAC secret" } } } }, "/api/v1/tenant/webhooks/{id}": { "get": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "Get Webhook Configuration", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Webhook details" } } }, "delete": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "Delete Webhook Subscription", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Webhook deleted" } } } }, "/api/v1/tenant/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "Rotate Webhook HMAC Secret", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Dual-secret rotation period initiated" } } } }, "/api/v1/tenant/webhooks/dlq": { "get": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "Inspect Dead-Letter Queue", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Quarantined failed deliveries" } } } }, "/api/v1/tenant/webhooks/dlq/{eventId}/replay": { "post": { "tags": [ "Group 8: Webhooks & DLQ" ], "summary": "Replay Dead-Letter Queue Event", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Event redelivered" } } } }, "/api/v1/break-glass": { "post": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Submit Emergency Break-Glass Request", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreakGlassFulfillmentRequest" } } } }, "responses": { "200": { "description": "Emergency access granted with tamper audit token" } } } }, "/api/v1/break-glass/audit": { "get": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Query Break-Glass Audit Trail", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Caldicott-compliant emergency audit events" } } } }, "/api/v1/break-glass-config": { "get": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Get Break-Glass Configuration", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Current emergency access policy" } } }, "put": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Update Break-Glass Configuration", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Emergency access policy updated" } } } }, "/api/v1/tenant/break-glass-config": { "get": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "List Tenant Break-Glass Eligibility Rules", "description": "Query all configured resource and permission break-glass eligibility rules with TTL and witness requirements.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Break-glass eligibility rules list" } } }, "post": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Create or Update Break-Glass Rule", "description": "Insert or update emergency escalation rule with TTL and max duration constraints.", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Rule registered" } } } }, "/api/v1/tenant/break-glass-config/{ruleId}": { "delete": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Delete Break-Glass Rule", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "ruleId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rule removed" } } } }, "/api/v1/break-glass/active": { "get": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "List Active Emergency Sessions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Currently active emergency overrides" } } } }, "/api/v1/break-glass/revoke": { "post": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Revoke Active Emergency Session", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Emergency access revoked instantly" } } } }, "/api/v1/break-glass/historical": { "get": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Historical Break-Glass Log", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Historical sessions" } } } }, "/api/v1/break-glass/tamper-check": { "get": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Cryptographic Non-Repudiation Check", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Cryptographic verification status" } } } }, "/api/v1/break-glass/verify-tsa": { "post": { "tags": [ "Group 9: Break-Glass REST" ], "summary": "Verify RFC 3161 Timestamp Token", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "RFC 3161 TSA verification token valid" } } } }, "/api/v1/tenant/policies": { "get": { "tags": [ "Group 10: Policy Administration" ], "summary": "List Schema Policy Definitions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Object type definitions list" } } }, "post": { "tags": [ "Group 10: Policy Administration" ], "summary": "Create Policy Definition", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Policy object type created" } } } }, "/api/v1/tenant/policies/{objectType}": { "get": { "tags": [ "Group 10: Policy Administration" ], "summary": "Get Policy Definition", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Object type definition" } } }, "put": { "tags": [ "Group 10: Policy Administration" ], "summary": "Update Policy Definition", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Object type definition updated" } } }, "delete": { "tags": [ "Group 10: Policy Administration" ], "summary": "Delete Policy Definition", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Object type definition removed" } } } }, "/api/v1/tenant/policies/history": { "get": { "tags": [ "Group 10: Policy Administration" ], "summary": "Schema Modification History", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Paginated schema version audit trail" } } } }, "/api/v1/tenant/policies/export": { "get": { "tags": [ "Group 10: Policy Administration" ], "summary": "Export SpiceDB .zed Schema File", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Standard SpiceDB schema DSL file" } } } }, "/.well-known/openid-configuration": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "Root OIDC Discovery Document", "responses": { "200": { "description": "Standard OpenID Connect metadata" } } } }, "/t/{tenant_id}/.well-known/openid-configuration": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "Tenant-Scoped OIDC Discovery Document", "responses": { "200": { "description": "Tenant-specific metadata" } } } }, "/.well-known/jwks.json": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "Platform JSON Web Key Set (JWKS)", "responses": { "200": { "description": "Public verification keys" } } } }, "/.well-known/oauth-authorization-server": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "RFC 8414 Authorization Server Metadata", "responses": { "200": { "description": "Token exchange, DPoP and RAR capabilities" } } } }, "/.well-known/oauth-protected-resource": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "RFC 9728 Protected Resource Metadata", "responses": { "200": { "description": "MCP and AI tool resource server discovery" } } } }, "/.well-known/ssf-configuration": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "OpenID Shared Signals and Events (CAEP)", "responses": { "200": { "description": "SSF transmitter configuration" } } } }, "/discovery/v1/tenants": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "Multi-Region Tenant Routing Discovery", "responses": { "200": { "description": "Routing endpoints across regions" } } } }, "/discovery/v1/tenants/{tenant_id}": { "get": { "tags": [ "Group 11: OIDC Discovery" ], "summary": "Inspect Specific Tenant Region Binding", "responses": { "200": { "description": "Regional egress target" } } } }, "/api/v1/tenant/hsm/status": { "get": { "tags": [ "Group 12: HSM & BYOK" ], "summary": "HSM Partition Health & Session Pool", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "FIPS 140-2 Level 3 HSM partition telemetry" } } } }, "/api/operator/keys": { "get": { "tags": [ "Group 12: HSM & BYOK" ], "summary": "Operator Cryptographic Key Status", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active and retained signing keys" } } } }, "/api/v1/operator/keys/rotate": { "post": { "tags": [ "Group 12: HSM & BYOK" ], "summary": "Trigger Zero-Downtime Key Rotation", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Key rotation initiated" } } } }, "/api/v1/tenant/hsm/import": { "post": { "tags": [ "Group 12: HSM & BYOK" ], "summary": "Import BYOK Key with Envelope Wrapping", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Key imported into PKCS#11 partition" } } } }, "/api/v1/tenant/cimd/policies/create": { "post": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Create Client ID Document Admission Policy", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Admission rule created" } } } }, "/api/v1/tenant/cimd/policies/list": { "get": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "List CIMD Admission Policies", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active policies and quota usage" } } } }, "/api/v1/tenant/cimd/policies/update": { "post": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Update CIMD Admission Policy", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Policy updated" } } } }, "/api/v1/tenant/cimd/policies/delete": { "post": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Delete CIMD Admission Policy", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Policy removed" } } } }, "/api/v1/tenant/billing": { "get": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Get Subscription & Plan State", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active plan, billing period, and status" } } } }, "/api/v1/tenant/billing/checkout": { "post": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Create Stripe Checkout Session", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Stripe Checkout URL" } } } }, "/api/v1/tenant/billing/portal": { "post": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Open Stripe Customer Billing Portal", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Portal session URL" } } } }, "/api/v1/tenant/billing/invoices": { "get": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "List Billing Invoices & Receipts", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Invoice history" } } } }, "/api/v1/tenant/billing/downgrade": { "post": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Schedule End-of-Period Tier Downgrade", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Downgrade scheduled" } } } }, "/api/v1/tenant/profile": { "get": { "tags": [ "Group 13: CIMD & Billing" ], "summary": "Get Tenant Profile & Subscription Tier", "description": "Fetches organization details, active billing plan, and isolation parameters.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tenant profile configuration" } } } }, "/health": { "get": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Health & Readiness Probe", "description": "Comprehensive cluster diagnostic checking CockroachDB, Redis, SpiceDB, and Kafka brokers.", "responses": { "200": { "description": "System healthy and ready" }, "503": { "description": "Subsystem degraded or unavailable" } } } }, "/metrics": { "get": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Prometheus Exposition Metrics", "description": "Standard Prometheus text exposition format.", "responses": { "200": { "description": "Prometheus metrics text" } } } }, "/auth/login": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Administrative Authentication", "description": "Authenticates administrative credentials and sets secure HttpOnly cookie session.", "responses": { "200": { "description": "Login successful" } } } }, "/auth/refresh": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Refresh Administrative Token", "responses": { "200": { "description": "Token refreshed" } } } }, "/auth/logout": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Administrative Logout", "responses": { "200": { "description": "Session terminated" } } } }, "/auth/register": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Self-Service Tenant Registration", "responses": { "201": { "description": "Tenant registered" } } } }, "/auth/verify-email": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Verify Tenant Email", "responses": { "200": { "description": "Email verified" } } } }, "/auth/resend-code": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Resend Verification Code", "responses": { "200": { "description": "Code resent" } } } }, "/auth/forgot-password": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Forgot Password Request", "responses": { "200": { "description": "Reset email dispatched" } } } }, "/auth/reset-password": { "post": { "tags": [ "Group 14: Health & Diagnostics" ], "summary": "Reset Password", "responses": { "200": { "description": "Password updated" } } } }, "/api/v1/tenant/nhis": { "get": { "tags": [ "Specialist: NHI Management" ], "summary": "List Non-Human Identities (NHIs)", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "List of NHI machine identities" } } }, "post": { "tags": [ "Specialist: NHI Management" ], "summary": "Register Non-Human Identity (NHI)", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "NHI registered" } } } }, "/api/v1/tenant/nhis/{id}": { "get": { "tags": [ "Specialist: NHI Management" ], "summary": "Get NHI Profile", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "NHI profile" } } }, "put": { "tags": [ "Specialist: NHI Management" ], "summary": "Update NHI Configuration", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "NHI updated" } } }, "delete": { "tags": [ "Specialist: NHI Management" ], "summary": "Revoke Non-Human Identity", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "NHI revoked" } } } }, "/api/v1/tenant/governance/signals": { "get": { "tags": [ "Specialist: Governance Signals" ], "summary": "List Active Governance Signals", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active signal telemetry" } } }, "post": { "tags": [ "Specialist: Governance Signals" ], "summary": "Emit Real-Time Governance Signal", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Signal processed" } } } }, "/api/v1/tenant/governance/autonomous-policies": { "get": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "List Autonomous Governance Rules", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Configured self-healing policies" } } }, "post": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "Register Autonomous Policy", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Policy activated" } } } }, "/api/v1/tenant/governance/suspensions": { "get": { "tags": [ "Specialist: Governance Signals" ], "summary": "List Governance Suspensions", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active clinical and identity freezes" } } }, "post": { "tags": [ "Specialist: Governance Signals" ], "summary": "Enforce Governance Suspension", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Subject suspended" } } } }, "/api/v1/tenant/governance/drift-declarations": { "get": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "List Policy Drift Declarations", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Drift events and self-repair actions" } } } }, "/api/v1/tenant/governance/policies": { "get": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "List Three-Clock Governance Policies", "description": "Fetches contextual authorization policies matching trigger fields, required attestations, and auto-expiry durations.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Active governance policies" } } }, "post": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "Create Three-Clock Governance Policy", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Policy registered" } } } }, "/api/v1/tenant/governance/policies/{policyId}": { "delete": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "Deactivate Governance Policy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "policyId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Policy deactivated" } } } }, "/api/v1/tenant/governance/break-glass": { "post": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "Emergency Override Bypassing Governance Suspension", "description": "Sets a short-lived key in Redis overriding governance suspensions for emergency care.", "security": [ { "BearerAuth": [] } ], "responses": { "201": { "description": "Emergency override activated" } } } }, "/api/v1/tenant/governance/audit": { "get": { "tags": [ "Specialist: Autonomous Governance" ], "summary": "Query Governance Audit Log", "description": "Immutable audit trail of governance suspensions, re-attestations, and emergency overrides.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Governance audit log records" } } } }, "/api/v1/tenant/test-suites": { "get": { "tags": [ "Specialist: Continuous Testing" ], "summary": "List Continuous Testing Tiers", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Tier health, pass rates, and cadence" } } }, "post": { "tags": [ "Specialist: Continuous Testing" ], "summary": "Trigger On-Demand Test Run", "security": [ { "BearerAuth": [] } ], "responses": { "202": { "description": "Test tier execution scheduled" } } } }, "/api/tenant/testing/mcp-gateway": { "get": { "tags": [ "Specialist: Continuous Testing" ], "summary": "Live MCP Gateway Protocol & RFC 9728 Synthetic Diagnostic Probe", "description": "Runs a 5-step end-to-end diagnostic probe against the live MCP gateway: RFC 9728 protected resource metadata, MCP 2026-07-28 server/discover handshake, RFC 9728 / RFC 6750 401 WWW-Authenticate challenge parsing, OIDC Discovery 1.0 schema compliance, and RFC 8693 ID-JAG token exchange.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Diagnostic probe execution summary with detailed assertion results" } } }, "post": { "tags": [ "Specialist: Continuous Testing" ], "summary": "Trigger Live MCP Gateway Synthetic Diagnostic Probe", "description": "Triggers on-demand synthetic execution of the 5-step MCP gateway protocol test.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Diagnostic probe execution summary" } } } }, "/api/v1/tenant/database-connections": { "get": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "List Registered Database Connections", "description": "Retrieves all registered enterprise database connections for the tenant, including active gateway URLs and governance status.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] } ], "responses": { "200": { "description": "List of registered database connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/DatabaseConnectionResponse" } } } } } } }, "401": { "description": "Unauthorized or missing tenant header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "Register Cloud Database Connection", "description": "Registers an external enterprise database (e.g. Aiven PostgreSQL, AWS RDS, Cloud SQL) with live credential connectivity testing, schema introspection, and SpiceDB governance bindings.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseConnectionRegistrationRequest" } } } }, "responses": { "200": { "description": "Database connection already registered (idempotent configuration update)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseConnectionResponse" } } } }, "201": { "description": "Database successfully tested, registered, and assigned a secure AuthHub Gateway URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseConnectionResponse" } } } }, "400": { "description": "Invalid configuration payload or unsupported database type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Live connection test failed against target database host", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/tenant/database-connections/{id}/query": { "post": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "Execute Gated Database Query", "description": "Executes a Text-to-SQL or parameterized query through AuthHub AuthZEN SARC evaluation, AST safety checks, SpiceDB ReBAC permission evaluation, and in-flight HMAC-SHA256 PII masking.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] }, { "UserIdentityHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique database connection identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseQueryRequest" } } } }, "responses": { "200": { "description": "Query permitted, executed against backend database, and results returned with PII masked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseQueryResponse" } } } }, "403": { "description": "Access denied by SpiceDB ReBAC, Clock-1 kill-switch, or AST safety rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Database connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/api/v1/tenant/database-connections/{id}/kill-switch": { "post": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "Trigger or Reset Database Gateway Kill Switch", "description": "Immediately suspends or restores all AI agent and workload access to this database gateway in sub-millisecond execution time.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique database connection identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseKillSwitchRequest" } } } }, "responses": { "200": { "description": "Kill switch state updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseKillSwitchResponse" } } } }, "404": { "description": "Database connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/tenant/database-connections": { "get": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "List Registered Database Connections", "description": "Direct alias for /api/v1/tenant/database-connections. Retrieves all registered enterprise database connections for the tenant.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] } ], "responses": { "200": { "description": "List of registered database connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/DatabaseConnectionResponse" } } } } } } }, "401": { "description": "Unauthorized or missing tenant header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "Register Cloud Database Connection", "description": "Direct alias for /api/v1/tenant/database-connections. Registers an external enterprise database with live connectivity testing, schema introspection, and SpiceDB governance bindings.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseConnectionRegistrationRequest" } } } }, "responses": { "200": { "description": "Database connection already registered (idempotent configuration update)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseConnectionResponse" } } } }, "201": { "description": "Database successfully tested, registered, and assigned a secure AuthHub Gateway URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseConnectionResponse" } } } }, "400": { "description": "Invalid configuration payload or unsupported database type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Live connection test failed against target database host", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/tenant/database-connections/{id}/query": { "post": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "Execute Gated Database Query", "description": "Direct alias for /api/v1/tenant/database-connections/{id}/query. Executes a Text-to-SQL or parameterized query through AuthZEN SARC evaluation, AST safety checks, SpiceDB ReBAC evaluation, and HMAC PII masking.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] }, { "UserIdentityHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique database connection identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseQueryRequest" } } } }, "responses": { "200": { "description": "Query permitted, executed against backend database, and results returned with PII masked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseQueryResponse" } } } }, "403": { "description": "Access denied by SpiceDB ReBAC, Clock-1 kill-switch, or AST safety rules", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Database connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/tenant/database-connections/{id}/kill-switch": { "post": { "tags": [ "Specialist: Database Access Gateways" ], "summary": "Trigger or Reset Database Gateway Kill Switch", "description": "Direct alias for /api/v1/tenant/database-connections/{id}/kill-switch. Immediately suspends or restores all AI agent and workload access to this database gateway in sub-millisecond execution time.", "security": [ { "BearerAuth": [] }, { "TenantIdHeader": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique database connection identifier" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseKillSwitchRequest" } } } }, "responses": { "200": { "description": "Kill switch state updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatabaseKillSwitchResponse" } } } }, "404": { "description": "Database connection not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } } }