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"