openapi: 3.1.0
info:
  description: OpenAPI-first public contract for tenant-facing B2B2X API surfaces.
    Terminology and resource semantics are sourced from b2b2x-mono.
  summary: Tenant-facing public API for the B2B2X platform.
  title: B2B2X Public API
  version: 0.1.0
servers:
  - description: Sandbox
    url: https://b2b2x-sandbox.youhodler.com/api
tags:
  - name: Activation
    description: Enterprise onboarding and initial tenant topology.
  - name: Setup
    description: Identity, access, policy, and approval setup.
  - name: Distribution
    description: Client onboarding, funding setup, and integration readiness.
  - name: Live Operations
    description: Deposits, withdrawals, conversions, and ramp flows.
  - name: Settlement
    description: Balance visibility, review, and operational settlement support.
  - name: Suspension
    description: Controlled deactivation, revocation, and closure flows.
  - name: Auth
    description: Token issuance for public API access.
  - name: Approvals
    description: Approval cases and decision operations.
  - name: Balances
    description: Composite owner balance views for financial accounts.
  - name: Capabilities
    description: Capability listing and client capability overrides.
  - name: Clients
    description: Downstream client resources scoped under an enterprise.
  - name: Client Accounts
    description: Financial operating accounts attached to clients.
  - name: Conversions
    description: Asset-to-asset conversion previews and execution.
  - name: External Settlement Conversions
    description: Conversions that can be connected to an external settlement source
      when an enterprise needs that settlement model. Contact your account
      manager for availability and setup details.
  - name: Deposits
    description: Inbound transactions crediting tenant accounts.
  - name: Deposit Instructions
    description: Resolved deposit-side wiring published to senders.
  - name: Enterprises
    description: Enterprise resources and lifecycle.
  - name: Events
    description: Tenant-visible platform event log and webhook replay operations.
  - name: Fee Previews
    description: Indicative, non-binding fee calculations.
  - name: Funding Endpoints
    description: Provisioned deposit-side endpoints for supported rails.
  - name: Identity Providers
    description: Federated identity provider registration and lookup.
  - name: Internal Transfers
    description: Money movement between tenant financial accounts.
  - name: Master Accounts
    description: Enterprise and platform-operator financial operating accounts.
  - name: Prices
    description: Indicative price discovery for asset pairs.
  - name: Roles
    description: Role definitions and access control assignment.
  - name: Role Assignments
    description: Role grants bound to principals and topology scope.
  - name: Service Accounts
    description: Non-human integration actors for backend API use.
  - name: Users
    description: Human actors operating within tenant boundaries.
  - name: Webhook Subscriptions
    description: Webhook subscription configuration and delivery recovery.
  - name: Withdrawals
    description: Outbound transactions debiting tenant accounts.
  - name: Withdrawal Destinations
    description: Persistent destinations referenced when initiating a withdrawal.
  - name: User Invitations
    description: E-mail invitation flows for onboarding new users into a tenant.
  - name: On-ramp Sessions
    description: Fiat-in or crypto-in flows that convert external funds into an
      account balance.
  - name: Me
    description: Current-caller introspection endpoints for capabilities and navigation.
  - name: Action Tokens
    description: Short-lived action tokens for delegated approval and governed
      follow-up actions.
  - name: Commercial Agreements
    description: Enterprise commercial agreement lifecycle and supersession.
  - name: Conversion Pairs
    description: Supported conversion pair discovery and lookup.
  - name: Crypto Networks
    description: Crypto network listing and eligibility surfaces.
  - name: Payment Methods
    description: Payment method registration and lifecycle management.
  - name: Payout Methods
    description: Payout method registration and lifecycle management.
  - name: Policies
    description: Policy rule creation, activation, and retirement.
  - name: Operations Activity Exports
    description: Asynchronous export of operations activity data.
  - name: User Action Audit Entries
    description: Search and inspect user action audit trail entries.
  - name: User Action Audit Exports
    description: Asynchronous export of user action audit data.
  - name: Audit
    description: Cross-cutting audit trail surfaces.
  - name: Reporting
    description: Cross-cutting reporting and analytics surfaces.
  - name: Off-ramp Sessions
    description: Crypto-out or fiat-out flows that convert an account balance into
      external funds.
  - name: Sandbox
    description: Simulate external decisions and transfers in sandbox only. These
      routes return 404 in production.
paths:
  /action-tokens:
    post:
      description: >-
        Issues a short-lived action token that authorises a specific
        money-movement command. The token is bound to the caller and to the
        command digest of the requested action. Pass it in the `X-Action-Token`
        header when submitting the authorised command (e.g. `POST
        /withdrawals`). Pure service callers have no human-confirmation
        requirement and do not obtain action tokens: issuance requires a human
        subject and rejects a pure service subject with HTTP 403.


        Enterprise/client human callers whose session does not satisfy the
        scope-level MFA assurance policy receive `401` with `code =
        insufficient_user_authentication`; follow the `WWW-Authenticate` header
        `acr_values` and `max_age` challenge, complete step-up at the IdP, then
        retry this request. Platform-bound humans always meet a mandatory MFA
        floor.


        Request shapes, in order of preference:

        - `{ action: "<command>", command: { ... } }` — edge validates the
        command and computes the digest server-side. Submit the same command
        values to the guarded endpoint. Object key order is canonicalized;
        withdrawal commands also normalize the money and destination fields
        before hashing. Supported commands:
          - `withdrawal.create` → `POST /withdrawals`
          - `conversion.create` → `POST /conversions`
          - `external_settlement_conversion.create` → `POST /external-settlement-conversions`
        - `{ action: "withdrawal.create", withdrawal: { ... } }` — the original
        withdrawal-only field name, kept for compatibility; issues the same
        digest as the generic form.

        - `{ command_digest: "..." }` — escape hatch for guarded commands with
        no structured variant yet. Callers must reproduce edge canonicalisation
        themselves, so prefer the structured form wherever one exists. Digests
        are hexadecimal SHA-256 values without a sha256: prefix.


        Tokens are bound to the human subject and command, expire after five
        minutes and can be consumed once. Credential issuance bypasses durable
        idempotency response caching. Each request issues a fresh single-use
        token; retries must obtain and use a fresh token.
      summary: Issue action token
      tags:
        - Live Operations
        - Action Tokens
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              action: conversion.create
              command:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                from_amount:
                  currency: USDT
                  value: "100.00"
                to_currency: BTC
            schema:
              examples:
                - action: conversion.create
                  command:
                    account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    from_amount:
                      currency: USDT
                      value: "100.00"
                    to_currency: BTC
              anyOf:
                - required:
                    - action
                    - command
                  type: object
                  additionalProperties: false
                  properties:
                    action:
                      type: string
                      const: withdrawal.create
                    command:
                      anyOf:
                        - required:
                            - amount
                            - account_ref
                            - rail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            destination:
                              required:
                                - address
                              type: object
                              additionalProperties: false
                              properties:
                                address:
                                  type: string
                                  minLength: 1
                                memo:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            destination_id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            network:
                              type: string
                              minLength: 1
                            rail:
                              type: string
                              enum:
                                - crypto
                                - fiat
                        - required:
                            - amount
                            - account_ref
                            - withdrawal_destination_id
                            - rail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            rail:
                              type: string
                              const: fiat
                            withdrawal_destination_id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                - required:
                    - action
                    - command
                  type: object
                  additionalProperties: false
                  properties:
                    action:
                      type: string
                      const: conversion.create
                    command:
                      required:
                        - from_amount
                        - to_currency
                        - account_ref
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        client_idempotency_key:
                          type: string
                          minLength: 1
                        from_amount:
                          required:
                            - value
                            - currency
                          type: object
                          additionalProperties: false
                          properties:
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            value:
                              description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        to_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                - required:
                    - action
                    - command
                  type: object
                  additionalProperties: false
                  properties:
                    action:
                      type: string
                      const: external_settlement_conversion.create
                    command:
                      required:
                        - source_amount
                        - target_currency
                        - account_ref
                        - external_settlement_role
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        client_idempotency_key:
                          type: string
                          minLength: 1
                        external_settlement_role:
                          type: string
                          enum:
                            - external_source_spend
                            - external_target_disbursement
                        source_amount:
                          required:
                            - value
                            - currency
                          type: object
                          additionalProperties: false
                          properties:
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            value:
                              description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        target_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                - required:
                    - action
                    - withdrawal
                  type: object
                  additionalProperties: false
                  properties:
                    action:
                      type: string
                      const: withdrawal.create
                    withdrawal:
                      anyOf:
                        - required:
                            - amount
                            - account_ref
                            - rail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            destination:
                              required:
                                - address
                              type: object
                              additionalProperties: false
                              properties:
                                address:
                                  type: string
                                  minLength: 1
                                memo:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            destination_id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            network:
                              type: string
                              minLength: 1
                            rail:
                              type: string
                              enum:
                                - crypto
                                - fiat
                        - required:
                            - amount
                            - account_ref
                            - withdrawal_destination_id
                            - rail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            rail:
                              type: string
                              const: fiat
                            withdrawal_destination_id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                - required:
                    - command_digest
                  type: object
                  additionalProperties: false
                  properties:
                    command_digest:
                      description: Pre-computed command digest. Escape hatch for guarded commands with
                        no structured variant yet — prefer the `action` form,
                        which covers withdrawal.create, conversion.create,
                        external_settlement_conversion.create.
                      type: string
                      minLength: 1
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                bound_actor: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                bound_command_digest: a67a92ab1ea536ece3702cb97990040a45948c453aeb585e5ed1d8f2ce7734af
                expires_at: 2026-05-01T10:00:00Z
                token: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
              schema:
                required:
                  - token
                  - bound_actor
                  - bound_command_digest
                  - expires_at
                type: object
                additionalProperties: false
                properties:
                  bound_actor:
                    type: string
                  bound_command_digest:
                    type: string
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  token:
                    type: string
                examples:
                  - bound_actor: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    bound_command_digest: a67a92ab1ea536ece3702cb97990040a45948c453aeb585e5ed1d8f2ce7734af
                    expires_at: 2026-05-01T10:00:00Z
                    token: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/InsufficientUserAuthentication"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: action_tokens.create
      x-mfa-assurance:
        challenge: insufficient_user_authentication
        gated: true
        surface: action_token.issue
  /approvals:
    get:
      description: Lists approval cases visible in the required topology scope. Repeat
        status to select several states. The edge accepts approvals.read or
        approvals.decide; tenant queues still require read authority over the
        requested scope, while the platform queue also admits its authorized
        deciders.
      summary: List approvals
      tags:
        - Setup
        - Approvals
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - pending
                  - approved
                  - rejected
                  - cancelled
                  - expired
              - type: array
                items:
                  type: string
                  enum:
                    - pending
                    - approved
                    - rejected
                    - cancelled
                    - expired
        - name: operation_id
          in: query
          required: false
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - action_family: withdrawal
                    collected_human_approvals: 0
                    created_at: 2026-05-01T10:00:00Z
                    decision: null
                    expires_at: 2026-05-02T10:00:00Z
                    governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    initiated_by:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requirement_snapshot:
                      authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      expires_at: 2026-05-02T10:00:00Z
                      governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      initiator_cannot_approve: true
                      reason_code: high_value
                      required_human_approvals: 1
                      requirement_key: withdrawal_approval
                      source: policy
                    resource: approval
                    status: pending
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - action_family
                        - operation_id
                        - governed_ref
                        - initiated_by
                        - requirement_snapshot
                        - collected_human_approvals
                        - created_at
                        - updated_at
                        - expires_at
                      type: object
                      additionalProperties: false
                      properties:
                        action_family:
                          type: string
                          minLength: 1
                        collected_human_approvals:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        decision:
                          anyOf:
                            - type: object
                              additionalProperties: false
                              properties:
                                decided_at:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: "null"
                                decided_by:
                                  anyOf:
                                    - required:
                                        - authenticated_principal
                                        - subject
                                        - actor
                                        - initiated_by
                                        - approved_by
                                        - identity_source
                                        - federation
                                        - enterprise_binding
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        actor:
                                          anyOf:
                                            - required:
                                                - id
                                                - kind
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                id:
                                                  type: string
                                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                                  format: uuid
                                                kind:
                                                  type: string
                                                  enum:
                                                    - user
                                                    - service
                                                    - system
                                                tenant_ref:
                                                  anyOf:
                                                    - type: string
                                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                                    - type: "null"
                                            - type: "null"
                                        approved_by:
                                          anyOf:
                                            - required:
                                                - id
                                                - kind
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                id:
                                                  type: string
                                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                                  format: uuid
                                                kind:
                                                  type: string
                                                  enum:
                                                    - user
                                                    - service
                                                    - system
                                                tenant_ref:
                                                  anyOf:
                                                    - type: string
                                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                                    - type: "null"
                                            - type: "null"
                                        authenticated_principal:
                                          required:
                                            - id
                                            - kind
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            id:
                                              type: string
                                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                              format: uuid
                                            kind:
                                              type: string
                                              enum:
                                                - user
                                                - service
                                                - system
                                            tenant_ref:
                                              anyOf:
                                                - type: string
                                                  pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                                - type: "null"
                                        enterprise_binding:
                                          required:
                                            - topology_ref
                                            - tenant_type
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            tenant_type:
                                              type: string
                                              enum:
                                                - enterprise
                                                - platform_operator
                                            topology_ref:
                                              anyOf:
                                                - type: string
                                                  pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                                - type: "null"
                                        federation:
                                          anyOf:
                                            - required:
                                                - issuer
                                                - external_subject
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                external_subject:
                                                  type: string
                                                  minLength: 1
                                                issuer:
                                                  type: string
                                                  minLength: 1
                                            - type: "null"
                                        identity_source:
                                          type: string
                                          enum:
                                            - platform-managed
                                            - federated
                                            - system
                                        initiated_by:
                                          anyOf:
                                            - required:
                                                - id
                                                - kind
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                id:
                                                  type: string
                                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                                  format: uuid
                                                kind:
                                                  type: string
                                                  enum:
                                                    - user
                                                    - service
                                                    - system
                                                tenant_ref:
                                                  anyOf:
                                                    - type: string
                                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                                    - type: "null"
                                            - type: "null"
                                        subject:
                                          anyOf:
                                            - required:
                                                - id
                                                - kind
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                id:
                                                  type: string
                                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                                  format: uuid
                                                kind:
                                                  type: string
                                                  enum:
                                                    - user
                                                    - service
                                                    - system
                                                tenant_ref:
                                                  anyOf:
                                                    - type: string
                                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                                    - type: "null"
                                            - type: "null"
                                    - type: "null"
                                reason:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        expires_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        governed_ref:
                          anyOf:
                            - type: string
                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        initiated_by:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                            - federation
                            - enterprise_binding
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            authenticated_principal:
                              required:
                                - id
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                tenant_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            enterprise_binding:
                              required:
                                - topology_ref
                                - tenant_type
                              type: object
                              additionalProperties: false
                              properties:
                                tenant_type:
                                  type: string
                                  enum:
                                    - enterprise
                                    - platform_operator
                                topology_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            federation:
                              anyOf:
                                - required:
                                    - issuer
                                    - external_subject
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    external_subject:
                                      type: string
                                      minLength: 1
                                    issuer:
                                      type: string
                                      minLength: 1
                                - type: "null"
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                        operation_id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        requirement_snapshot:
                          required:
                            - source
                            - requirement_key
                            - governed_ref
                            - authority_ref
                            - required_human_approvals
                            - reason_code
                            - initiator_cannot_approve
                          type: object
                          additionalProperties: false
                          properties:
                            approver_role_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            authority_ref:
                              type: string
                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            expires_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: "null"
                            governed_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: string
                                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            initiator_cannot_approve:
                              type: boolean
                            reason_code:
                              type: string
                              minLength: 1
                            required_human_approvals:
                              type: integer
                              maximum: 9007199254740991
                              exclusiveMinimum: 0
                            requirement_key:
                              type: string
                              minLength: 1
                            source:
                              type: string
                              const: policy
                        resource:
                          type: string
                          const: approval
                        status:
                          type: string
                          enum:
                            - pending
                            - approved
                            - rejected
                            - cancelled
                            - expired
                        subject_display:
                          anyOf:
                            - required:
                                - current_email
                                - new_email
                              type: object
                              additionalProperties: false
                              properties:
                                current_email:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                      format: email
                                    - type: "null"
                                new_email:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                      format: email
                                    - type: "null"
                            - type: "null"
                        subject_ref:
                          anyOf:
                            - type: string
                              pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - action_family: withdrawal
                        collected_human_approvals: 0
                        created_at: 2026-05-01T10:00:00Z
                        decision: null
                        expires_at: 2026-05-02T10:00:00Z
                        governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        initiated_by:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        requirement_snapshot:
                          authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          expires_at: 2026-05-02T10:00:00Z
                          governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          initiator_cannot_approve: true
                          reason_code: high_value
                          required_human_approvals: 1
                          requirement_key: withdrawal_approval
                          source: policy
                        resource: approval
                        status: pending
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: approvals.list
      x-required-capability-any-of:
        - - approvals.read
          - approvals.decide
  /approvals/{approval_id}:
    get:
      description: Reads a visible approval case. The edge accepts approvals.read or
        approvals.decide; downstream visibility checks still apply to its
        governed scope. collected_human_approvals records the distinct people
        who have approved against requirement_snapshot.required_human_approvals.
      summary: Get approval
      tags:
        - Setup
        - Approvals
      security:
        - BearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                action_family: withdrawal
                collected_human_approvals: 0
                created_at: 2026-05-01T10:00:00Z
                decision: null
                expires_at: 2026-05-02T10:00:00Z
                governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                initiated_by:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requirement_snapshot:
                  authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  expires_at: 2026-05-02T10:00:00Z
                  governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  initiator_cannot_approve: true
                  reason_code: high_value
                  required_human_approvals: 1
                  requirement_key: withdrawal_approval
                  source: policy
                resource: approval
                status: pending
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - action_family
                  - operation_id
                  - governed_ref
                  - initiated_by
                  - requirement_snapshot
                  - collected_human_approvals
                  - created_at
                  - updated_at
                  - expires_at
                type: object
                additionalProperties: false
                properties:
                  action_family:
                    type: string
                    minLength: 1
                  collected_human_approvals:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  decision:
                    anyOf:
                      - type: object
                        additionalProperties: false
                        properties:
                          decided_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: "null"
                          decided_by:
                            anyOf:
                              - required:
                                  - authenticated_principal
                                  - subject
                                  - actor
                                  - initiated_by
                                  - approved_by
                                  - identity_source
                                  - federation
                                  - enterprise_binding
                                type: object
                                additionalProperties: false
                                properties:
                                  actor:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  approved_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  authenticated_principal:
                                    required:
                                      - id
                                      - kind
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                        format: uuid
                                      kind:
                                        type: string
                                        enum:
                                          - user
                                          - service
                                          - system
                                      tenant_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  enterprise_binding:
                                    required:
                                      - topology_ref
                                      - tenant_type
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      tenant_type:
                                        type: string
                                        enum:
                                          - enterprise
                                          - platform_operator
                                      topology_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  federation:
                                    anyOf:
                                      - required:
                                          - issuer
                                          - external_subject
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          external_subject:
                                            type: string
                                            minLength: 1
                                          issuer:
                                            type: string
                                            minLength: 1
                                      - type: "null"
                                  identity_source:
                                    type: string
                                    enum:
                                      - platform-managed
                                      - federated
                                      - system
                                  initiated_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  subject:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  governed_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  initiated_by:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  operation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requirement_snapshot:
                    required:
                      - source
                      - requirement_key
                      - governed_ref
                      - authority_ref
                      - required_human_approvals
                      - reason_code
                      - initiator_cannot_approve
                    type: object
                    additionalProperties: false
                    properties:
                      approver_role_ref:
                        anyOf:
                          - type: string
                            pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      authority_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      expires_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      governed_ref:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      initiator_cannot_approve:
                        type: boolean
                      reason_code:
                        type: string
                        minLength: 1
                      required_human_approvals:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                      requirement_key:
                        type: string
                        minLength: 1
                      source:
                        type: string
                        const: policy
                  resource:
                    type: string
                    const: approval
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - rejected
                      - cancelled
                      - expired
                  subject_display:
                    anyOf:
                      - required:
                          - current_email
                          - new_email
                        type: object
                        additionalProperties: false
                        properties:
                          current_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                      - type: "null"
                  subject_ref:
                    anyOf:
                      - type: string
                        pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - action_family: withdrawal
                    collected_human_approvals: 0
                    created_at: 2026-05-01T10:00:00Z
                    decision: null
                    expires_at: 2026-05-02T10:00:00Z
                    governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    initiated_by:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requirement_snapshot:
                      authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      expires_at: 2026-05-02T10:00:00Z
                      governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      initiator_cannot_approve: true
                      reason_code: high_value
                      required_human_approvals: 1
                      requirement_key: withdrawal_approval
                      source: policy
                    resource: approval
                    status: pending
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: approvals.get
      x-required-capability-any-of:
        - - approvals.read
          - approvals.decide
  /approvals/{approval_id}/approve:
    post:
      description: Records an eligible human approval on a pending case. The caller
        needs approvals.decide, scope coverage and any role named in the
        requirement snapshot; initiator_cannot_approve excludes the initiator
        when enabled. The case stays pending until enough distinct human
        approvals are collected, then becomes approved. MFA assurance applies to
        this decision surface; a step-up challenge is returned when the current
        session does not meet the resolved requirement.
      summary: Approve approval
      tags:
        - Setup
        - Approvals
      security:
        - BearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: Reviewed request
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - reason: Reviewed request
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                action_family: withdrawal
                collected_human_approvals: 1
                created_at: 2026-05-01T10:00:00Z
                decision:
                  decided_at: 2026-05-01T10:00:00Z
                  decided_by:
                    actor: null
                    approved_by: null
                    authenticated_principal:
                      id: 11111111-1111-4111-8111-111111111111
                      kind: user
                      tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    enterprise_binding:
                      tenant_type: enterprise
                      topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    federation: null
                    identity_source: platform-managed
                    initiated_by: null
                    subject:
                      id: 11111111-1111-4111-8111-111111111111
                      kind: user
                      tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  reason: Approved after review
                expires_at: 2026-05-02T10:00:00Z
                governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                initiated_by:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requirement_snapshot:
                  authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  expires_at: 2026-05-02T10:00:00Z
                  governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  initiator_cannot_approve: true
                  reason_code: high_value
                  required_human_approvals: 1
                  requirement_key: withdrawal_approval
                  source: policy
                resource: approval
                status: approved
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - action_family
                  - operation_id
                  - governed_ref
                  - initiated_by
                  - requirement_snapshot
                  - collected_human_approvals
                  - created_at
                  - updated_at
                  - expires_at
                type: object
                additionalProperties: false
                properties:
                  action_family:
                    type: string
                    minLength: 1
                  collected_human_approvals:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  decision:
                    anyOf:
                      - type: object
                        additionalProperties: false
                        properties:
                          decided_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: "null"
                          decided_by:
                            anyOf:
                              - required:
                                  - authenticated_principal
                                  - subject
                                  - actor
                                  - initiated_by
                                  - approved_by
                                  - identity_source
                                  - federation
                                  - enterprise_binding
                                type: object
                                additionalProperties: false
                                properties:
                                  actor:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  approved_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  authenticated_principal:
                                    required:
                                      - id
                                      - kind
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                        format: uuid
                                      kind:
                                        type: string
                                        enum:
                                          - user
                                          - service
                                          - system
                                      tenant_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  enterprise_binding:
                                    required:
                                      - topology_ref
                                      - tenant_type
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      tenant_type:
                                        type: string
                                        enum:
                                          - enterprise
                                          - platform_operator
                                      topology_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  federation:
                                    anyOf:
                                      - required:
                                          - issuer
                                          - external_subject
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          external_subject:
                                            type: string
                                            minLength: 1
                                          issuer:
                                            type: string
                                            minLength: 1
                                      - type: "null"
                                  identity_source:
                                    type: string
                                    enum:
                                      - platform-managed
                                      - federated
                                      - system
                                  initiated_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  subject:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  governed_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  initiated_by:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  operation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requirement_snapshot:
                    required:
                      - source
                      - requirement_key
                      - governed_ref
                      - authority_ref
                      - required_human_approvals
                      - reason_code
                      - initiator_cannot_approve
                    type: object
                    additionalProperties: false
                    properties:
                      approver_role_ref:
                        anyOf:
                          - type: string
                            pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      authority_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      expires_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      governed_ref:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      initiator_cannot_approve:
                        type: boolean
                      reason_code:
                        type: string
                        minLength: 1
                      required_human_approvals:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                      requirement_key:
                        type: string
                        minLength: 1
                      source:
                        type: string
                        const: policy
                  resource:
                    type: string
                    const: approval
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - rejected
                      - cancelled
                      - expired
                  subject_display:
                    anyOf:
                      - required:
                          - current_email
                          - new_email
                        type: object
                        additionalProperties: false
                        properties:
                          current_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                      - type: "null"
                  subject_ref:
                    anyOf:
                      - type: string
                        pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - action_family: withdrawal
                    collected_human_approvals: 1
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      decided_at: 2026-05-01T10:00:00Z
                      decided_by:
                        actor: null
                        approved_by: null
                        authenticated_principal:
                          id: 11111111-1111-4111-8111-111111111111
                          kind: user
                          tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        enterprise_binding:
                          tenant_type: enterprise
                          topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        federation: null
                        identity_source: platform-managed
                        initiated_by: null
                        subject:
                          id: 11111111-1111-4111-8111-111111111111
                          kind: user
                          tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      reason: Approved after review
                    expires_at: 2026-05-02T10:00:00Z
                    governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    initiated_by:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requirement_snapshot:
                      authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      expires_at: 2026-05-02T10:00:00Z
                      governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      initiator_cannot_approve: true
                      reason_code: high_value
                      required_human_approvals: 1
                      requirement_key: withdrawal_approval
                      source: policy
                    resource: approval
                    status: approved
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/InsufficientUserAuthentication"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: approvals.approve
      x-mfa-assurance:
        challenge: insufficient_user_authentication
        gated: true
        surface: approval.decide
      x-required-capability:
        - approvals.decide
  /approvals/{approval_id}/cancel:
    post:
      description: Cancels a pending case on behalf of its original initiator. The
        edge requires approvals.decide; downstream also verifies that the caller
        is the original initiator. An optional nullable reason may be supplied.
        This route has no approval-decision MFA assurance gate.
      summary: Cancel approval
      tags:
        - Setup
        - Approvals
      security:
        - BearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: Reviewed request
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - reason: Reviewed request
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                action_family: withdrawal
                collected_human_approvals: 0
                created_at: 2026-05-01T10:00:00Z
                decision:
                  decided_at: 2026-05-01T10:00:00Z
                  decided_by: null
                  reason: Cancelled by the original initiator
                expires_at: 2026-05-02T10:00:00Z
                governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                initiated_by:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requirement_snapshot:
                  authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  expires_at: 2026-05-02T10:00:00Z
                  governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  initiator_cannot_approve: true
                  reason_code: high_value
                  required_human_approvals: 1
                  requirement_key: withdrawal_approval
                  source: policy
                resource: approval
                status: cancelled
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - action_family
                  - operation_id
                  - governed_ref
                  - initiated_by
                  - requirement_snapshot
                  - collected_human_approvals
                  - created_at
                  - updated_at
                  - expires_at
                type: object
                additionalProperties: false
                properties:
                  action_family:
                    type: string
                    minLength: 1
                  collected_human_approvals:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  decision:
                    anyOf:
                      - type: object
                        additionalProperties: false
                        properties:
                          decided_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: "null"
                          decided_by:
                            anyOf:
                              - required:
                                  - authenticated_principal
                                  - subject
                                  - actor
                                  - initiated_by
                                  - approved_by
                                  - identity_source
                                  - federation
                                  - enterprise_binding
                                type: object
                                additionalProperties: false
                                properties:
                                  actor:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  approved_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  authenticated_principal:
                                    required:
                                      - id
                                      - kind
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                        format: uuid
                                      kind:
                                        type: string
                                        enum:
                                          - user
                                          - service
                                          - system
                                      tenant_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  enterprise_binding:
                                    required:
                                      - topology_ref
                                      - tenant_type
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      tenant_type:
                                        type: string
                                        enum:
                                          - enterprise
                                          - platform_operator
                                      topology_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  federation:
                                    anyOf:
                                      - required:
                                          - issuer
                                          - external_subject
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          external_subject:
                                            type: string
                                            minLength: 1
                                          issuer:
                                            type: string
                                            minLength: 1
                                      - type: "null"
                                  identity_source:
                                    type: string
                                    enum:
                                      - platform-managed
                                      - federated
                                      - system
                                  initiated_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  subject:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  governed_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  initiated_by:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  operation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requirement_snapshot:
                    required:
                      - source
                      - requirement_key
                      - governed_ref
                      - authority_ref
                      - required_human_approvals
                      - reason_code
                      - initiator_cannot_approve
                    type: object
                    additionalProperties: false
                    properties:
                      approver_role_ref:
                        anyOf:
                          - type: string
                            pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      authority_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      expires_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      governed_ref:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      initiator_cannot_approve:
                        type: boolean
                      reason_code:
                        type: string
                        minLength: 1
                      required_human_approvals:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                      requirement_key:
                        type: string
                        minLength: 1
                      source:
                        type: string
                        const: policy
                  resource:
                    type: string
                    const: approval
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - rejected
                      - cancelled
                      - expired
                  subject_display:
                    anyOf:
                      - required:
                          - current_email
                          - new_email
                        type: object
                        additionalProperties: false
                        properties:
                          current_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                      - type: "null"
                  subject_ref:
                    anyOf:
                      - type: string
                        pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - action_family: withdrawal
                    collected_human_approvals: 0
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      decided_at: 2026-05-01T10:00:00Z
                      decided_by: null
                      reason: Cancelled by the original initiator
                    expires_at: 2026-05-02T10:00:00Z
                    governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    initiated_by:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requirement_snapshot:
                      authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      expires_at: 2026-05-02T10:00:00Z
                      governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      initiator_cannot_approve: true
                      reason_code: high_value
                      required_human_approvals: 1
                      requirement_key: withdrawal_approval
                      source: policy
                    resource: approval
                    status: cancelled
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: approvals.cancel
      x-required-capability:
        - approvals.decide
  /approvals/{approval_id}/eligible-approvers:
    get:
      description: Lists currently eligible human approvers for the case, subject to
        approvals.read and visibility of its governed scope. Eligibility
        reflects decide capability, scope coverage, any named approver role and
        the initiator exclusion. Results are paginated; eligibility is checked
        again when a decision is submitted.
      summary: List eligible approvers
      tags:
        - Setup
        - Approvals
      security:
        - BearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - display_name: Jane Smith
                    eligibility_basis: role_assignment
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: human_actor
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - eligibility_basis
                      type: object
                      additionalProperties: false
                      properties:
                        display_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        eligibility_basis:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        resource:
                          type: string
                          const: human_actor
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - display_name: Jane Smith
                        eligibility_basis: role_assignment
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: human_actor
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: approvals.eligible_approvers
      x-required-capability:
        - approvals.read
  /approvals/{approval_id}/reject:
    post:
      description: Rejects a pending case with one eligible human decision, regardless
        of the approval quorum. The caller needs approvals.decide, scope
        coverage and any role named in the requirement snapshot;
        initiator_cannot_approve excludes the initiator when enabled. MFA
        assurance applies to this decision surface; a step-up challenge is
        returned when the current session does not meet the resolved
        requirement.
      summary: Reject approval
      tags:
        - Setup
        - Approvals
      security:
        - BearerAuth: []
      parameters:
        - name: approval_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: Reviewed request
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - reason: Reviewed request
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                action_family: withdrawal
                collected_human_approvals: 0
                created_at: 2026-05-01T10:00:00Z
                decision:
                  decided_at: 2026-05-01T10:00:00Z
                  decided_by:
                    actor: null
                    approved_by: null
                    authenticated_principal:
                      id: 11111111-1111-4111-8111-111111111111
                      kind: user
                      tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    enterprise_binding:
                      tenant_type: enterprise
                      topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    federation: null
                    identity_source: platform-managed
                    initiated_by: null
                    subject:
                      id: 11111111-1111-4111-8111-111111111111
                      kind: user
                      tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  reason: Rejected after review
                expires_at: 2026-05-02T10:00:00Z
                governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                initiated_by:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requirement_snapshot:
                  authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  expires_at: 2026-05-02T10:00:00Z
                  governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  initiator_cannot_approve: true
                  reason_code: high_value
                  required_human_approvals: 1
                  requirement_key: withdrawal_approval
                  source: policy
                resource: approval
                status: rejected
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - action_family
                  - operation_id
                  - governed_ref
                  - initiated_by
                  - requirement_snapshot
                  - collected_human_approvals
                  - created_at
                  - updated_at
                  - expires_at
                type: object
                additionalProperties: false
                properties:
                  action_family:
                    type: string
                    minLength: 1
                  collected_human_approvals:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  decision:
                    anyOf:
                      - type: object
                        additionalProperties: false
                        properties:
                          decided_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: "null"
                          decided_by:
                            anyOf:
                              - required:
                                  - authenticated_principal
                                  - subject
                                  - actor
                                  - initiated_by
                                  - approved_by
                                  - identity_source
                                  - federation
                                  - enterprise_binding
                                type: object
                                additionalProperties: false
                                properties:
                                  actor:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  approved_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  authenticated_principal:
                                    required:
                                      - id
                                      - kind
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      id:
                                        type: string
                                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                        format: uuid
                                      kind:
                                        type: string
                                        enum:
                                          - user
                                          - service
                                          - system
                                      tenant_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  enterprise_binding:
                                    required:
                                      - topology_ref
                                      - tenant_type
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      tenant_type:
                                        type: string
                                        enum:
                                          - enterprise
                                          - platform_operator
                                      topology_ref:
                                        anyOf:
                                          - type: string
                                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                          - type: "null"
                                  federation:
                                    anyOf:
                                      - required:
                                          - issuer
                                          - external_subject
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          external_subject:
                                            type: string
                                            minLength: 1
                                          issuer:
                                            type: string
                                            minLength: 1
                                      - type: "null"
                                  identity_source:
                                    type: string
                                    enum:
                                      - platform-managed
                                      - federated
                                      - system
                                  initiated_by:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                                  subject:
                                    anyOf:
                                      - required:
                                          - id
                                          - kind
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          id:
                                            type: string
                                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                            format: uuid
                                          kind:
                                            type: string
                                            enum:
                                              - user
                                              - service
                                              - system
                                          tenant_ref:
                                            anyOf:
                                              - type: string
                                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                              - type: "null"
                                      - type: "null"
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  governed_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  initiated_by:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  operation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requirement_snapshot:
                    required:
                      - source
                      - requirement_key
                      - governed_ref
                      - authority_ref
                      - required_human_approvals
                      - reason_code
                      - initiator_cannot_approve
                    type: object
                    additionalProperties: false
                    properties:
                      approver_role_ref:
                        anyOf:
                          - type: string
                            pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      authority_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      expires_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      governed_ref:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      initiator_cannot_approve:
                        type: boolean
                      reason_code:
                        type: string
                        minLength: 1
                      required_human_approvals:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                      requirement_key:
                        type: string
                        minLength: 1
                      source:
                        type: string
                        const: policy
                  resource:
                    type: string
                    const: approval
                  status:
                    type: string
                    enum:
                      - pending
                      - approved
                      - rejected
                      - cancelled
                      - expired
                  subject_display:
                    anyOf:
                      - required:
                          - current_email
                          - new_email
                        type: object
                        additionalProperties: false
                        properties:
                          current_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                      - type: "null"
                  subject_ref:
                    anyOf:
                      - type: string
                        pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - action_family: withdrawal
                    collected_human_approvals: 0
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      decided_at: 2026-05-01T10:00:00Z
                      decided_by:
                        actor: null
                        approved_by: null
                        authenticated_principal:
                          id: 11111111-1111-4111-8111-111111111111
                          kind: user
                          tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        enterprise_binding:
                          tenant_type: enterprise
                          topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        federation: null
                        identity_source: platform-managed
                        initiated_by: null
                        subject:
                          id: 11111111-1111-4111-8111-111111111111
                          kind: user
                          tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      reason: Rejected after review
                    expires_at: 2026-05-02T10:00:00Z
                    governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    initiated_by:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requirement_snapshot:
                      authority_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      expires_at: 2026-05-02T10:00:00Z
                      governed_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      initiator_cannot_approve: true
                      reason_code: high_value
                      required_human_approvals: 1
                      requirement_key: withdrawal_approval
                      source: policy
                    resource: approval
                    status: rejected
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/InsufficientUserAuthentication"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: approvals.reject
      x-mfa-assurance:
        challenge: insufficient_user_authentication
        gated: true
        surface: approval.decide
      x-required-capability:
        - approvals.decide
  /available-crypto-networks:
    get:
      description: Returns active crypto networks projected from available runtime
        asset/rail tuples for the required operating account. direction defaults
        to deposit and also accepts withdrawal. When asset is supplied, each
        item contains only assets that passed that filter and availability
        check. Account coverage is checked against an authenticated enterprise
        tenant binding; unbound and platform-operator callers receive 403, and
        an account outside the tenant receives 404. This is a current snapshot
        for the selected direction; funding-endpoint provisioning and withdrawal
        submission recheck their own requirements.
      summary: List available crypto networks
      tags:
        - Distribution
        - Crypto Networks
      security:
        - BearerAuth: []
      parameters:
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - deposit
              - withdrawal
            default: deposit
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    assets:
                      - USDC
                    code: ethereum
                    display_name: Ethereum
                  - active: true
                    assets:
                      - USDC
                    code: polygon
                    display_name: Polygon
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - code
                        - display_name
                        - active
                        - assets
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        assets:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                        code:
                          type: string
                          minLength: 1
                        display_name:
                          type: string
                          minLength: 1
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        assets:
                          - USDC
                        code: ethereum
                        display_name: Ethereum
                      - active: true
                        assets:
                          - USDC
                        code: polygon
                        display_name: Polygon
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: available_crypto_networks.list
  /available-payment-methods:
    get:
      description: Returns fiat deposit methods whose current runtime availability
        permits setup for the supplied `account_ref`. The account must lie
        within the caller’s bound enterprise or client scope; an out-of-scope
        account returns `404 resource_not_found`, and an unbound or
        platform-bound caller is refused. This is a current setup-readiness
        signal, not a guarantee that a later deposit succeeds. Use
        `/payment-methods` for the global reference catalog.
      summary: List available payment methods
      tags:
        - Distribution
        - Payment Methods
      security:
        - BearerAuth: []
      parameters:
        - name: rail
          in: query
          required: false
          schema:
            type: string
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    code: sepa_credit_transfer
                    currencies:
                      - EUR
                    display_name: SEPA
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail: sepa_credit_transfer
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - code
                        - display_name
                        - rail
                        - currencies
                        - active
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        code:
                          type: string
                          pattern: ^[a-z0-9_]+$
                        currencies:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          minItems: 1
                        display_name:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        code: sepa_credit_transfer
                        currencies:
                          - EUR
                        display_name: SEPA
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail: sepa_credit_transfer
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: available_payment_methods.list
  /capabilities:
    get:
      description: Lists feature enablement flags for the requested topology node,
        sorted by name. enabled resolves the platform default/override,
        enterprise override and client override chain; disabled entries remain
        visible. Requires feature_flags.read with scope coverage. These catalog
        flags do not describe the caller's role grants; use GET /me/capabilities
        for current effective RBAC authority. page_size defaults to 100 (maximum
        200).
      summary: List capabilities
      tags:
        - Setup
        - Capabilities
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - name: deposit_fiat
                    enabled: true
                  - name: staking
                    enabled: false
                  - name: withdrawal
                    enabled: true
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - name
                        - enabled
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          minLength: 1
                        enabled:
                          type: boolean
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - name: deposit_fiat
                        enabled: true
                      - name: staking
                        enabled: false
                      - name: withdrawal
                        enabled: true
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: capabilities.list
      x-required-capability:
        - feature_flags.read
  /client-accounts:
    get:
      description: List financial operating accounts attached to a client. The
        `scope_ref` query parameter is required and accepts a `clients/{uuid}`
        resource ref.
      summary: List client accounts
      tags:
        - Distribution
        - Client Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - suspended
                  - closed
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - suspended
                    - closed
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Operating Account
                    etag: 2026-05-01T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: client_account
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - scope_ref
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        display_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        etag:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        resource:
                          type: string
                          const: client_account
                        scope_ref:
                          type: string
                          pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - suspended
                            - closed
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - created_at: 2026-05-01T10:00:00Z
                        display_name: Operating Account
                        etag: 2026-05-01T10:00:00Z
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: client_account
                        scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.list
      x-required-capability:
        - accounts.read
    post:
      description: The metadata field is accepted but is currently ignored and not
        persisted. Creates an additional operating account under the named
        active client. The first default account is created with the client;
        this route adds a sibling. Requires the Idempotency-Key header.
      summary: Create client account
      tags:
        - Distribution
        - Client Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Client-generated key, 1-128 characters. Accepted on POST requests
            and required where marked. For the same concrete path and
            caller/subject/tenant scope, an identical body replays the original
            status and body; a different body returns 409 idempotency_conflict.
            Keep query parameters unchanged when retrying.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            example:
              display_name: Operating Account EUR
              scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - scope_ref
              type: object
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                metadata:
                  anyOf:
                    - type: object
                      additionalProperties: {}
                      propertyNames:
                        type: string
                    - type: "null"
                scope_ref:
                  type: string
                  pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - display_name: Operating Account EUR
                  scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Operating Account
                etag: 2026-05-01T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: client_account
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  resource:
                    type: string
                    const: client_account
                  scope_ref:
                    type: string
                    pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Operating Account
                    etag: 2026-05-01T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: client_account
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.create
      x-required-capability:
        - accounts.create
  /client-accounts/{client_account_id}:
    get:
      summary: Get client account
      tags:
        - Distribution
        - Client Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: client_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Operating Account
                etag: 2026-05-01T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: client_account
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  resource:
                    type: string
                    const: client_account
                  scope_ref:
                    type: string
                    pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Operating Account
                    etag: 2026-05-01T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: client_account
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.get
      x-required-capability:
        - accounts.read
  /client-accounts/{client_account_id}/balances:
    get:
      description: "Returns balances for a client account. Pass `?asset=USDC` to fetch
        a single balance; an omitted or empty asset returns the assets with
        operating or withdrawal-hold ledger rows. A requested asset without a
        matching ledger position returns 404. The response preserves ledger
        availability semantics: `available` excludes held funds, while `held`
        and `total` remain explicit and total = available + held. Internal
        conversion holds are excluded from these public totals. The
        accounts.read grant must cover the account or the call returns 404."
      summary: Get client-account balances
      tags:
        - Settlement
        - Balances
      security:
        - BearerAuth: []
      parameters:
        - name: client_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: asset
          in: query
          required: false
          schema:
            anyOf:
              - description: Currency code (ISO-4217 or on-chain ticker)
                type: string
                pattern: ^[A-Z0-9]{1,16}$
              - type: string
                const: ""
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - asset: USDC
                    available: "950.00"
                    held: "50.00"
                    overdraft_headroom: null
                    overdraft_limit: null
                    overdraft_used: null
                    owner_ref: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    owner_subtype: client_account
                    total: "1000.00"
                    updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - owner_ref
                        - owner_subtype
                        - asset
                        - available
                        - held
                        - total
                        - updated_at
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        available:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        held:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        overdraft_headroom:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        overdraft_limit:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        overdraft_used:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        owner_ref:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        owner_subtype:
                          type: string
                          enum:
                            - master_account
                            - client_account
                            - treasury
                        total:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                examples:
                  - items:
                      - asset: USDC
                        available: "950.00"
                        held: "50.00"
                        overdraft_headroom: null
                        overdraft_limit: null
                        overdraft_used: null
                        owner_ref: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        owner_subtype: client_account
                        total: "1000.00"
                        updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.balances
      x-required-capability:
        - accounts.read
  /client-accounts/{client_account_id}/close:
    post:
      summary: Close client account
      tags:
        - Distribution
        - Client Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: client_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Operating Account
                etag: 2026-05-01T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: client_account
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: closed
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  resource:
                    type: string
                    const: client_account
                  scope_ref:
                    type: string
                    pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Operating Account
                    etag: 2026-05-01T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: client_account
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: closed
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.close
      x-required-capability:
        - accounts.manage
  /client-accounts/{client_account_id}/external-settlement-balances:
    get:
      description: Returns current external funding spend authority for a client
        account. This endpoint is separate from ledger balances, is
        informational, and provider unavailability is surfaced as
        provider_unavailable (503) instead of a zero balance. The read resolves
        the external_source_spend binding. Currency is optional; unsupported
        currency returns unsupported_currency (422). Missing binding,
        external-funding mode, or client mapping returns 404. The caller needs
        accounts.read coverage on the client account. available, held, and total
        are decimal strings in the item currency; held and total may be absent.
        This snapshot neither reserves funds nor guarantees later execution.
      summary: List client-account external funding balances
      tags:
        - Settlement
        - External Funding
      security:
        - BearerAuth: []
      parameters:
        - name: client_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: currency
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/00000000-0000-4000-8000-000000000001
                    as_of: 2026-05-01T10:00:00Z
                    available: "950.00"
                    currency: EUR
                    held: "50.00"
                    source: external_settlement
                    total: "1000.00"
              schema:
                required:
                  - items
                description: External settlement balance reads are informational spend-authority
                  reads. Provider unavailability is surfaced as a typed error
                  and is not mapped to zero balance.
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - account_ref
                        - currency
                        - available
                        - as_of
                        - source
                      description: External settlement balance reads are informational spend-authority
                        reads. Provider unavailability is surfaced as a typed
                        error and is not mapped to zero balance.
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        as_of:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        available:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        held:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        source:
                          type: string
                          const: external_settlement
                        total:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                examples:
                  - items:
                      - account_ref: client-accounts/00000000-0000-4000-8000-000000000001
                        as_of: 2026-05-01T10:00:00Z
                        available: "950.00"
                        currency: EUR
                        held: "50.00"
                        source: external_settlement
                        total: "1000.00"
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.external_settlement_balances
      x-required-capability:
        - accounts.read
  /client-accounts/{client_account_id}/reactivate:
    post:
      summary: Reactivate client account
      tags:
        - Distribution
        - Client Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: client_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Operating Account
                etag: 2026-05-01T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: client_account
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  resource:
                    type: string
                    const: client_account
                  scope_ref:
                    type: string
                    pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Operating Account
                    etag: 2026-05-01T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: client_account
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.reactivate
      x-required-capability:
        - accounts.manage
  /client-accounts/{client_account_id}/suspend:
    post:
      summary: Suspend client account
      tags:
        - Distribution
        - Client Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: client_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Operating Account
                etag: 2026-05-01T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: client_account
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: suspended
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  resource:
                    type: string
                    const: client_account
                  scope_ref:
                    type: string
                    pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Operating Account
                    etag: 2026-05-01T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: client_account
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: suspended
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: client_accounts.suspend
      x-required-capability:
        - accounts.manage
  /clients:
    get:
      description: List tenant clients under an enterprise scope. `kyc_source`,
        `kyb_source` and `kyb_state_reason` (the verification provider and its
        reason) are present only for callers holding this operation’s capability
        through an `enterprise_wildcard` grant anchored at
        `platform-operators/<id>` (platform staff); other callers receive the
        client without them.
      summary: List clients
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - suspended
                  - closed
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - suspended
                    - closed
        - name: external_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
        - name: q
          in: query
          required: false
          schema:
            type: string
        - name: verification
          in: query
          required: false
          schema:
            type: string
            enum:
              - verified
              - in_progress
              - unverified
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-001
                      tier: premium
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - scope_ref
                        - kyc_stage
                        - kyb_stage
                        - kyb_state
                        - kyb_state_updated_at
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        default_client_account:
                          anyOf:
                            - type: string
                              pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        display_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        etag:
                          type: string
                          minLength: 1
                        external_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        kyb_source:
                          description: Present only for callers with platform-wide authority; omitted for
                            tenant callers.
                          anyOf:
                            - type: string
                              enum:
                                - bootstrap
                                - sumsub
                            - type: "null"
                        kyb_stage:
                          anyOf:
                            - type: string
                              enum:
                                - form_k_ready
                                - verified
                            - type: "null"
                        kyb_state:
                          anyOf:
                            - type: string
                              enum:
                                - not_started
                                - in_progress
                                - submitted
                                - in_review
                                - resubmission_required
                                - form_k_ready
                                - verified
                                - rejected
                            - type: "null"
                        kyb_state_reason:
                          description: Present only for callers with platform-wide authority; omitted for
                            tenant callers.
                          anyOf:
                            - type: string
                            - type: "null"
                        kyb_state_updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        kyc_source:
                          description: Present only for callers with platform-wide authority; omitted for
                            tenant callers.
                          anyOf:
                            - type: string
                              enum:
                                - bootstrap
                                - sumsub
                            - type: "null"
                        kyc_stage:
                          anyOf:
                            - type: string
                              enum:
                                - verified
                            - type: "null"
                        metadata:
                          anyOf:
                            - type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            - type: "null"
                        resource:
                          type: string
                          const: client
                        scope_ref:
                          type: string
                          pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - suspended
                            - closed
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - created_at: 2026-05-01T10:00:00Z
                        default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        display_name: Acme Corp
                        etag: 2026-05-01T10:00:00Z
                        external_id: ext-client-0042
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kyb_stage: null
                        kyb_state: null
                        kyb_state_updated_at: null
                        kyc_stage: null
                        metadata:
                          crm_id: CRM-001
                          tier: premium
                        resource: client
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.list
      x-required-capability:
        - clients.read
    post:
      description: Create a client under an enterprise. The first default client
        account is provisioned atomically. Requires the Idempotency-Key header.
        Read-only verification stamps and workflow state are returned separately
        from partner-writable metadata. `kyc_source`, `kyb_source` and
        `kyb_state_reason` (the verification provider and its reason) are
        present only for callers holding this operation’s capability through an
        `enterprise_wildcard` grant anchored at `platform-operators/<id>`
        (platform staff); other callers receive the client without them.
      summary: Create client
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Client-generated key, 1-128 characters. Accepted on POST requests
            and required where marked. For the same concrete path and
            caller/subject/tenant scope, an identical body replays the original
            status and body; a different body returns 409 idempotency_conflict.
            Keep query parameters unchanged when retrying.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            example:
              display_name: Acme Corp
              external_id: ext-client-0042
              metadata:
                crm_id: CRM-001
                tier: premium
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - scope_ref
              type: object
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                external_id:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: "null"
                metadata:
                  anyOf:
                    - type: object
                      additionalProperties: {}
                      propertyNames:
                        type: string
                    - type: "null"
                scope_ref:
                  type: string
                  pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - display_name: Acme Corp
                  external_id: ext-client-0042
                  metadata:
                    crm_id: CRM-001
                    tier: premium
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                display_name: Acme Corp
                etag: 2026-05-01T10:00:00Z
                external_id: ext-client-0042
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kyb_stage: null
                kyb_state: null
                kyb_state_updated_at: null
                kyc_stage: null
                metadata:
                  crm_id: CRM-001
                  tier: premium
                resource: client
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_client_account:
                    anyOf:
                      - type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kyb_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: client
                  scope_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-001
                      tier: premium
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.create
      x-required-capability:
        - clients.create
  /clients/{client_id}:
    parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: Carries `first_access_method` of the client’s enterprise, from its
        onboarding record (`null` when there is none or it cannot be read).
        `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification
        provider and its reason) are present only for callers holding this
        operation’s capability through an `enterprise_wildcard` grant anchored
        at `platform-operators/<id>` (platform staff); other callers receive the
        client without them.
      summary: Get client
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                display_name: Acme Corp
                etag: 2026-05-01T10:00:00Z
                external_id: ext-client-0042
                first_access_method: enterprise_idp
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kyb_stage: null
                kyb_state: null
                kyb_state_updated_at: null
                kyc_stage: null
                metadata:
                  crm_id: CRM-001
                  tier: premium
                resource: client
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - created_at
                  - updated_at
                  - etag
                  - first_access_method
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_client_account:
                    anyOf:
                      - type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  first_access_method:
                    anyOf:
                      - type: string
                        enum:
                          - magic_link
                          - passkey_enrolment
                          - enterprise_idp
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kyb_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: client
                  scope_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    first_access_method: enterprise_idp
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-001
                      tier: premium
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.get
      x-required-capability:
        - clients.read
    patch:
      description: Patch tenant client. Requires `If-Match` for optimistic
        concurrency. `kyc_source`, `kyb_source` and `kyb_state_reason` (the
        verification provider and its reason) are present only for callers
        holding this operation’s capability through an `enterprise_wildcard`
        grant anchored at `platform-operators/<id>` (platform staff); other
        callers receive the client without them.
      summary: Update client
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            example:
              display_name: Acme Corp Updated
              metadata:
                crm_id: CRM-002
            schema:
              type: object
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                external_id:
                  anyOf:
                    - type: string
                    - type: "null"
                metadata:
                  anyOf:
                    - type: object
                      additionalProperties: {}
                      propertyNames:
                        type: string
                    - type: "null"
              examples:
                - display_name: Acme Corp Updated
                  metadata:
                    crm_id: CRM-002
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                display_name: Acme Corp Updated
                etag: 2026-05-01T10:00:00Z
                external_id: ext-client-0042
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kyb_stage: null
                kyb_state: null
                kyb_state_updated_at: null
                kyc_stage: null
                metadata:
                  crm_id: CRM-002
                resource: client
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_client_account:
                    anyOf:
                      - type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kyb_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: client
                  scope_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp Updated
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-002
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.update
      x-required-capability:
        - clients.manage
  /clients/{client_id}/capabilities/{capability_name}:
    patch:
      description: Retired endpoint. Every authenticated call returns 410
        deprecated_endpoint before reading the path or body; it cannot change a
        feature override. No request body or success response is supported.
      summary: Toggle capability override for client (deprecated)
      tags:
        - Setup
        - Capabilities
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
        - name: capability_name
          in: path
          required: true
          schema:
            type: string
      responses:
        "401":
          $ref: "#/components/responses/Unauthorized"
        "410":
          $ref: "#/components/responses/EdgeGone"
      deprecated: true
      operationId: clients.capabilities.update
  /clients/{client_id}/close:
    post:
      description: "`kyc_source`, `kyb_source` and `kyb_state_reason` (the
        verification provider and its reason) are present only for callers
        holding this operation’s capability through an `enterprise_wildcard`
        grant anchored at `platform-operators/<id>` (platform staff); other
        callers receive the client without them."
      summary: Close client
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                display_name: Acme Corp
                etag: 2026-05-01T10:00:00Z
                external_id: ext-client-0042
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kyb_stage: null
                kyb_state: null
                kyb_state_updated_at: null
                kyc_stage: null
                metadata:
                  crm_id: CRM-001
                  tier: premium
                resource: client
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: closed
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_client_account:
                    anyOf:
                      - type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kyb_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: client
                  scope_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-001
                      tier: premium
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: closed
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.close
      x-required-capability:
        - clients.manage
  /clients/{client_id}/mfa-assurance:
    parameters:
      - name: client_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: Read the MFA assurance setting for this scope. Requires
        policies.read covering the target scope. own_mode is null when this
        scope inherits its policy; effective_mode and source_scope_ref describe
        the resolved policy. owner identifies a scope-owned or platform-owned
        local row and is null when no local row exists. With no setting in the
        lineage, effective_mode is optional and source_scope_ref is null.
        Platform human sessions always have a mandatory MFA floor independent of
        these enterprise/client settings.
      summary: Read client MFA policy
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                effective_mode: mandatory
                own_mode: mandatory
                owner: scope
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                source_scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - scope_ref
                  - own_mode
                  - effective_mode
                  - source_scope_ref
                type: object
                additionalProperties: false
                properties:
                  effective_mode:
                    type: string
                    enum:
                      - optional
                      - mandatory
                  own_mode:
                    anyOf:
                      - type: string
                        enum:
                          - optional
                          - mandatory
                      - type: "null"
                  owner:
                    anyOf:
                      - type: string
                        enum:
                          - scope
                          - platform
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  source_scope_ref:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                examples:
                  - effective_mode: mandatory
                    own_mode: mandatory
                    owner: scope
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    source_scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.mfa_assurance.get
      x-required-capability:
        - policies.read
    put:
      description: Requires both policies.manage and policies.read covering the target
        scope; the current setting is read for the audit diff before writing.
        Set mode to inherited to remove the scope setting. Setting optional
        beneath a mandatory ancestor returns HTTP 409 with
        data.reason=mfa_cannot_relax and data.resource naming that ancestor. A
        platform-owned setting may only be changed by platform staff with
        platform-wide policies.manage authority; other callers receive HTTP 403
        with data.reason=mfa_setting_platform_owned. The required reason is
        trimmed and must contain 3 to 500 characters for the audit record. This
        changes the assurance policy; it does not enroll or remove an
        authentication factor.
      summary: Set client MFA policy
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            example:
              mode: mandatory
              reason: Require fresh authentication for protected actions
            schema:
              required:
                - mode
                - reason
              type: object
              additionalProperties: false
              properties:
                mode:
                  anyOf:
                    - type: string
                      const: inherited
                    - type: string
                      enum:
                        - optional
                        - mandatory
                reason:
                  type: string
                  minLength: 3
                  maxLength: 500
              examples:
                - mode: mandatory
                  reason: Require fresh authentication for protected actions
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                effective_mode: mandatory
                own_mode: mandatory
                owner: scope
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                source_scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - scope_ref
                  - own_mode
                  - effective_mode
                  - source_scope_ref
                type: object
                additionalProperties: false
                properties:
                  effective_mode:
                    type: string
                    enum:
                      - optional
                      - mandatory
                  own_mode:
                    anyOf:
                      - type: string
                        enum:
                          - optional
                          - mandatory
                      - type: "null"
                  owner:
                    anyOf:
                      - type: string
                        enum:
                          - scope
                          - platform
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  source_scope_ref:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                examples:
                  - effective_mode: mandatory
                    own_mode: mandatory
                    owner: scope
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    source_scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.mfa_assurance.set
      x-required-capability:
        - policies.manage
        - policies.read
  /clients/{client_id}/reactivate:
    post:
      description: "`kyc_source`, `kyb_source` and `kyb_state_reason` (the
        verification provider and its reason) are present only for callers
        holding this operation’s capability through an `enterprise_wildcard`
        grant anchored at `platform-operators/<id>` (platform staff); other
        callers receive the client without them."
      summary: Reactivate client
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                display_name: Acme Corp
                etag: 2026-05-01T10:00:00Z
                external_id: ext-client-0042
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kyb_stage: null
                kyb_state: null
                kyb_state_updated_at: null
                kyc_stage: null
                metadata:
                  crm_id: CRM-001
                  tier: premium
                resource: client
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_client_account:
                    anyOf:
                      - type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kyb_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: client
                  scope_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-001
                      tier: premium
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.reactivate
      x-required-capability:
        - clients.manage
  /clients/{client_id}/suspend:
    post:
      description: "`kyc_source`, `kyb_source` and `kyb_state_reason` (the
        verification provider and its reason) are present only for callers
        holding this operation’s capability through an `enterprise_wildcard`
        grant anchored at `platform-operators/<id>` (platform staff); other
        callers receive the client without them."
      summary: Suspend client
      tags:
        - Distribution
        - Clients
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                display_name: Acme Corp
                etag: 2026-05-01T10:00:00Z
                external_id: ext-client-0042
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kyb_stage: null
                kyb_state: null
                kyb_state_updated_at: null
                kyc_stage: null
                metadata:
                  crm_id: CRM-001
                  tier: premium
                resource: client
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: suspended
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_client_account:
                    anyOf:
                      - type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kyb_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide authority; omitted for
                      tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: client
                  scope_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    default_client_account: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    display_name: Acme Corp
                    etag: 2026-05-01T10:00:00Z
                    external_id: ext-client-0042
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kyb_stage: null
                    kyb_state: null
                    kyb_state_updated_at: null
                    kyc_stage: null
                    metadata:
                      crm_id: CRM-001
                      tier: premium
                    resource: client
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: suspended
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: clients.suspend
      x-required-capability:
        - clients.manage
  /conversion-pairs:
    get:
      description: Lists global product support corridors for conversions. Conversion
        pairs describe platform-supported source/target currency directions and
        static source amount bounds only; they are not account-specific
        eligibility, pricing, fee, liquidity, or execution guarantees. Omitting
        active selects active corridors; active=true and active=false are the
        supported boolean query spellings, with false selecting inactive
        corridors. Account and topology discovery parameters are rejected on
        this catalog route. Use conversion preflight/preview for
        account-specific availability and economics.
      summary: List conversion pairs
      tags:
        - Live Operations
        - Conversion Pairs
      security:
        - BearerAuth: []
      parameters:
        - name: source_currency
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: target_currency
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: active
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: string
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    display_order: 0
                    id: usdc-btc
                    max_source_amount: "100000.00"
                    min_source_amount: "10.00"
                    settlement_model: internal_platform
                    source_currency: USDC
                    target_currency: BTC
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - source_currency
                        - target_currency
                        - active
                        - min_source_amount
                        - max_source_amount
                        - display_order
                        - settlement_model
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        display_order:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        id:
                          type: string
                          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                          minLength: 1
                          maxLength: 128
                        max_source_amount:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        min_source_amount:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        settlement_model:
                          type: string
                          const: internal_platform
                        source_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        target_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        display_order: 0
                        id: usdc-btc
                        max_source_amount: "100000.00"
                        min_source_amount: "10.00"
                        settlement_model: internal_platform
                        source_currency: USDC
                        target_currency: BTC
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversion_pairs.list
  /conversion-pairs/{conversion_pair_id}:
    get:
      description: Returns one global product support corridor by its lowercase
        catalog id, such as usdc-btc. The ID is a string with lowercase
        alphanumeric segments separated by hyphens, not a UUID. This is static
        platform catalog data, not account-specific eligibility or a quote.
      summary: Get conversion pair
      tags:
        - Live Operations
        - Conversion Pairs
      security:
        - BearerAuth: []
      parameters:
        - name: conversion_pair_id
          in: path
          required: true
          schema:
            description: Stable lowercase catalog id for this corridor.
            type: string
            pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
            minLength: 1
            maxLength: 128
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                active: true
                display_order: 0
                id: usdc-btc
                max_source_amount: "100000.00"
                min_source_amount: "10.00"
                settlement_model: internal_platform
                source_currency: USDC
                target_currency: BTC
              schema:
                required:
                  - id
                  - source_currency
                  - target_currency
                  - active
                  - min_source_amount
                  - max_source_amount
                  - display_order
                  - settlement_model
                type: object
                additionalProperties: false
                properties:
                  active:
                    type: boolean
                  display_order:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  id:
                    type: string
                    pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
                    minLength: 1
                    maxLength: 128
                  max_source_amount:
                    description: DecimalString
                    type: string
                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  min_source_amount:
                    description: DecimalString
                    type: string
                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settlement_model:
                    type: string
                    const: internal_platform
                  source_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  target_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                examples:
                  - active: true
                    display_order: 0
                    id: usdc-btc
                    max_source_amount: "100000.00"
                    min_source_amount: "10.00"
                    settlement_model: internal_platform
                    source_currency: USDC
                    target_currency: BTC
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversion_pairs.get
  /conversions:
    get:
      description: Lists ledger-native conversion operation snapshots. Preview
        responses are informational only; operation execution may recompute fees
        and rate before ledger posting, so reads must not be treated as a bound
        preview replay.
      summary: List conversions
      tags:
        - Live Operations
        - Conversions
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    applied_rate: "0.00002"
                    approval_ref: null
                    conversion_execution_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    created_at: 2026-05-01T10:00:00Z
                    failure_detail: null
                    failure_reason: null
                    family: conversion
                    fee_summary:
                      components:
                        - amount:
                            currency: USD
                            value: "1.00"
                          kind: platform_fee
                      total:
                        currency: USD
                        value: "1.00"
                    fee_transaction_ids:
                      - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fill_rate: "0.00002"
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    ledger_posted_target_amount:
                      currency: BTC
                      value: "0.00498000"
                    leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    posted_at: 2026-05-01T10:00:00Z
                    principal_amount:
                      currency: USD
                      value: "250.00"
                    principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    settled_at: 2026-05-01T10:00:00Z
                    source_gross_amount:
                      currency: USD
                      value: "250.00"
                    source_principal_amount:
                      currency: USD
                      value: "249.00"
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_amount:
                      currency: BTC
                      value: "0.00498000"
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - family
                        - status
                        - account_ref
                        - principal_amount
                        - fee_summary
                        - fill_rate
                        - failure_reason
                        - settled_at
                        - approval_ref
                        - subject_attribution
                        - created_at
                        - updated_at
                        - target_currency
                        - leg_attempt_id
                        - conversion_execution_id
                        - source_gross_amount
                        - source_principal_amount
                        - target_amount
                        - ledger_posted_target_amount
                        - applied_rate
                        - principal_transaction_id
                        - fee_transaction_ids
                        - posted_at
                        - failure_detail
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        applied_rate:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        approval_ref:
                          anyOf:
                            - required:
                                - approval_id
                                - reason_code
                                - expires_at
                              type: object
                              additionalProperties: false
                              properties:
                                approval_id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                expires_at:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                reason_code:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        compliance_assessment_ref:
                          anyOf:
                            - type: string
                              pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        conversion_execution_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        failure_detail:
                          anyOf:
                            - required:
                                - stage
                                - reason_code
                                - retryable
                                - failed_at
                              type: object
                              additionalProperties: false
                              properties:
                                failed_at:
                                  anyOf:
                                    - anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    - type: "null"
                                reason_code:
                                  type: string
                                  pattern: ^[a-z0-9_.:-]+$
                                  minLength: 1
                                  maxLength: 128
                                retryable:
                                  anyOf:
                                    - type: boolean
                                    - type: "null"
                                stage:
                                  type: string
                                  enum:
                                    - pre_execution
                                    - execution
                                    - post_fill
                                    - ledger_posting
                                    - unknown
                            - type: "null"
                        failure_reason:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        family:
                          type: string
                          const: conversion
                        fee_summary:
                          anyOf:
                            - required:
                                - components
                                - total
                              type: object
                              additionalProperties: false
                              properties:
                                components:
                                  type: array
                                  items:
                                    required:
                                      - kind
                                      - amount
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      amount:
                                        required:
                                          - value
                                          - currency
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          currency:
                                            description: Currency code (ISO-4217 or on-chain ticker)
                                            type: string
                                            pattern: ^[A-Z0-9]{1,16}$
                                          value:
                                            description: DecimalString
                                            type: string
                                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                      kind:
                                        type: string
                                        enum:
                                          - platform_fee
                                          - enterprise_fee
                                          - network_fee
                                          - spread
                                total:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        fee_transaction_ids:
                          anyOf:
                            - type: array
                              items:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                            - type: "null"
                        fill_rate:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        ledger_posted_target_amount:
                          anyOf:
                            - required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        leg_attempt_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        posted_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        principal_amount:
                          required:
                            - value
                            - currency
                          type: object
                          additionalProperties: false
                          properties:
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            value:
                              description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        principal_transaction_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        settled_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        source_gross_amount:
                          anyOf:
                            - required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        source_principal_amount:
                          anyOf:
                            - required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        status:
                          type: string
                          enum:
                            - requested
                            - admissible
                            - executing
                            - pending_approval
                            - pending_admission
                            - pending_compliance
                            - executed
                            - settled
                            - ledger_visible
                            - failed
                            - cancelled
                            - partially_settled
                        subject_attribution:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                            - federation
                            - enterprise_binding
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            authenticated_principal:
                              required:
                                - id
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                tenant_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            enterprise_binding:
                              required:
                                - topology_ref
                                - tenant_type
                              type: object
                              additionalProperties: false
                              properties:
                                tenant_type:
                                  type: string
                                  enum:
                                    - enterprise
                                    - platform_operator
                                topology_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            federation:
                              anyOf:
                                - required:
                                    - issuer
                                    - external_subject
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    external_subject:
                                      type: string
                                      minLength: 1
                                    issuer:
                                      type: string
                                      minLength: 1
                                - type: "null"
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                        target_amount:
                          anyOf:
                            - required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        target_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        applied_rate: "0.00002"
                        approval_ref: null
                        conversion_execution_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        created_at: 2026-05-01T10:00:00Z
                        failure_detail: null
                        failure_reason: null
                        family: conversion
                        fee_summary:
                          components:
                            - amount:
                                currency: USD
                                value: "1.00"
                              kind: platform_fee
                          total:
                            currency: USD
                            value: "1.00"
                        fee_transaction_ids:
                          - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        fill_rate: "0.00002"
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        ledger_posted_target_amount:
                          currency: BTC
                          value: "0.00498000"
                        leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        posted_at: 2026-05-01T10:00:00Z
                        principal_amount:
                          currency: USD
                          value: "250.00"
                        principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        settled_at: 2026-05-01T10:00:00Z
                        source_gross_amount:
                          currency: USD
                          value: "250.00"
                        source_principal_amount:
                          currency: USD
                          value: "249.00"
                        status: settled
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        target_amount:
                          currency: BTC
                          value: "0.00498000"
                        target_currency: BTC
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversions.list
      x-required-capability:
        - conversions.read
    post:
      description: 'Initiates a ledger-native conversion with `account_ref`,
        `from_amount`, and `to_currency` only. Plain conversions never resolve
        external settlement facts or carry provider-settlement evidence; use
        `/external-settlement-conversions` for externally settled conversion
        roles. Any prior preview is non-binding: conversion execution may
        recompute fees and rate before ledger posting. The response is the
        current operation snapshot; after synchronous admission and dispatch the
        caller can see `admissible`, `pending_approval`, `pending_compliance`,
        or a terminal state such as `settled` or `failed`. Track it via `GET
        /conversions/{conversion_id}`. Supply `Idempotency-Key` or body
        `client_idempotency_key` for idempotent retries; the header takes
        precedence. If both are omitted, a fresh key is generated. Human callers
        must obtain a step-up confirmation via `POST /action-tokens` and submit
        it in the `X-Action-Token` header; use the structured body `{action:
        "conversion.create", command: <the same conversion body>}`; a matching
        `command_digest` is also accepted. Service principals are exempt.'
      summary: Create conversion
      tags:
        - Live Operations
        - Conversions
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/XActionToken"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              from_amount:
                currency: USD
                value: "250.00"
              to_currency: BTC
            schema:
              required:
                - from_amount
                - to_currency
                - account_ref
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                client_idempotency_key:
                  type: string
                  minLength: 1
                from_amount:
                  required:
                    - value
                    - currency
                  type: object
                  additionalProperties: false
                  properties:
                    currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    value:
                      description: DecimalString
                      type: string
                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                to_currency:
                  description: Currency code (ISO-4217 or on-chain ticker)
                  type: string
                  pattern: ^[A-Z0-9]{1,16}$
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  from_amount:
                    currency: USD
                    value: "250.00"
                  to_currency: BTC
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                applied_rate: null
                approval_ref: null
                conversion_execution_id: null
                created_at: 2026-05-01T10:00:00Z
                failure_detail: null
                failure_reason: null
                family: conversion
                fee_summary: null
                fee_transaction_ids: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                ledger_posted_target_amount: null
                leg_attempt_id: null
                posted_at: null
                principal_amount:
                  currency: USD
                  value: "250.00"
                principal_transaction_id: null
                settled_at: null
                source_gross_amount: null
                source_principal_amount: null
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                target_amount: null
                target_currency: BTC
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - target_currency
                  - leg_attempt_id
                  - conversion_execution_id
                  - source_gross_amount
                  - source_principal_amount
                  - target_amount
                  - ledger_posted_target_amount
                  - applied_rate
                  - principal_transaction_id
                  - fee_transaction_ids
                  - posted_at
                  - failure_detail
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  applied_rate:
                    anyOf:
                      - description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  conversion_execution_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_detail:
                    anyOf:
                      - required:
                          - stage
                          - reason_code
                          - retryable
                          - failed_at
                        type: object
                        additionalProperties: false
                        properties:
                          failed_at:
                            anyOf:
                              - anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              - type: "null"
                          reason_code:
                            type: string
                            pattern: ^[a-z0-9_.:-]+$
                            minLength: 1
                            maxLength: 128
                          retryable:
                            anyOf:
                              - type: boolean
                              - type: "null"
                          stage:
                            type: string
                            enum:
                              - pre_execution
                              - execution
                              - post_fill
                              - ledger_posting
                              - unknown
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: conversion
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fee_transaction_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  ledger_posted_target_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  leg_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  posted_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  principal_transaction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  source_gross_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  source_principal_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  target_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  target_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    applied_rate: null
                    approval_ref: null
                    conversion_execution_id: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_detail: null
                    failure_reason: null
                    family: conversion
                    fee_summary: null
                    fee_transaction_ids: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    ledger_posted_target_amount: null
                    leg_attempt_id: null
                    posted_at: null
                    principal_amount:
                      currency: USD
                      value: "250.00"
                    principal_transaction_id: null
                    settled_at: null
                    source_gross_amount: null
                    source_principal_amount: null
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_amount: null
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeActionTokenRequired"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversions.create
      x-required-capability:
        - conversions.create
  /conversions/{conversion_id}:
    get:
      description: Returns the current ledger-native conversion operation snapshot.
        Preview economics are non-binding display data; settled execution may
        use recomputed fees and rate before ledger posting.
      summary: Get conversion
      tags:
        - Live Operations
        - Conversions
      security:
        - BearerAuth: []
      parameters:
        - name: conversion_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                applied_rate: "0.00002"
                approval_ref: null
                conversion_execution_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                created_at: 2026-05-01T10:00:00Z
                failure_detail: null
                failure_reason: null
                family: conversion
                fee_summary:
                  components:
                    - amount:
                        currency: USD
                        value: "1.00"
                      kind: platform_fee
                  total:
                    currency: USD
                    value: "1.00"
                fee_transaction_ids:
                  - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                fill_rate: "0.00002"
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                ledger_posted_target_amount:
                  currency: BTC
                  value: "0.00498000"
                leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                posted_at: 2026-05-01T10:00:00Z
                principal_amount:
                  currency: USD
                  value: "250.00"
                principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                settled_at: 2026-05-01T10:00:00Z
                source_gross_amount:
                  currency: USD
                  value: "250.00"
                source_principal_amount:
                  currency: USD
                  value: "249.00"
                status: settled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                target_amount:
                  currency: BTC
                  value: "0.00498000"
                target_currency: BTC
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - target_currency
                  - leg_attempt_id
                  - conversion_execution_id
                  - source_gross_amount
                  - source_principal_amount
                  - target_amount
                  - ledger_posted_target_amount
                  - applied_rate
                  - principal_transaction_id
                  - fee_transaction_ids
                  - posted_at
                  - failure_detail
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  applied_rate:
                    anyOf:
                      - description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  conversion_execution_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_detail:
                    anyOf:
                      - required:
                          - stage
                          - reason_code
                          - retryable
                          - failed_at
                        type: object
                        additionalProperties: false
                        properties:
                          failed_at:
                            anyOf:
                              - anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              - type: "null"
                          reason_code:
                            type: string
                            pattern: ^[a-z0-9_.:-]+$
                            minLength: 1
                            maxLength: 128
                          retryable:
                            anyOf:
                              - type: boolean
                              - type: "null"
                          stage:
                            type: string
                            enum:
                              - pre_execution
                              - execution
                              - post_fill
                              - ledger_posting
                              - unknown
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: conversion
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fee_transaction_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  ledger_posted_target_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  leg_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  posted_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  principal_transaction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  source_gross_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  source_principal_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  target_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  target_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    applied_rate: "0.00002"
                    approval_ref: null
                    conversion_execution_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    created_at: 2026-05-01T10:00:00Z
                    failure_detail: null
                    failure_reason: null
                    family: conversion
                    fee_summary:
                      components:
                        - amount:
                            currency: USD
                            value: "1.00"
                          kind: platform_fee
                      total:
                        currency: USD
                        value: "1.00"
                    fee_transaction_ids:
                      - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fill_rate: "0.00002"
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    ledger_posted_target_amount:
                      currency: BTC
                      value: "0.00498000"
                    leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    posted_at: 2026-05-01T10:00:00Z
                    principal_amount:
                      currency: USD
                      value: "250.00"
                    principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    settled_at: 2026-05-01T10:00:00Z
                    source_gross_amount:
                      currency: USD
                      value: "250.00"
                    source_principal_amount:
                      currency: USD
                      value: "249.00"
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_amount:
                      currency: BTC
                      value: "0.00498000"
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversions.get
      x-required-capability:
        - conversions.read
  /conversions/{conversion_id}/cancel:
    post:
      summary: Cancel conversion
      tags:
        - Live Operations
        - Conversions
      security:
        - BearerAuth: []
      parameters:
        - name: conversion_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                applied_rate: null
                approval_ref: null
                conversion_execution_id: null
                created_at: 2026-05-01T10:00:00Z
                failure_detail: null
                failure_reason: null
                family: conversion
                fee_summary: null
                fee_transaction_ids: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                ledger_posted_target_amount: null
                leg_attempt_id: null
                posted_at: null
                principal_amount:
                  currency: USD
                  value: "250.00"
                principal_transaction_id: null
                settled_at: null
                source_gross_amount: null
                source_principal_amount: null
                status: cancelled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                target_amount: null
                target_currency: BTC
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - target_currency
                  - leg_attempt_id
                  - conversion_execution_id
                  - source_gross_amount
                  - source_principal_amount
                  - target_amount
                  - ledger_posted_target_amount
                  - applied_rate
                  - principal_transaction_id
                  - fee_transaction_ids
                  - posted_at
                  - failure_detail
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  applied_rate:
                    anyOf:
                      - description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  conversion_execution_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_detail:
                    anyOf:
                      - required:
                          - stage
                          - reason_code
                          - retryable
                          - failed_at
                        type: object
                        additionalProperties: false
                        properties:
                          failed_at:
                            anyOf:
                              - anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              - type: "null"
                          reason_code:
                            type: string
                            pattern: ^[a-z0-9_.:-]+$
                            minLength: 1
                            maxLength: 128
                          retryable:
                            anyOf:
                              - type: boolean
                              - type: "null"
                          stage:
                            type: string
                            enum:
                              - pre_execution
                              - execution
                              - post_fill
                              - ledger_posting
                              - unknown
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: conversion
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fee_transaction_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  ledger_posted_target_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  leg_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  posted_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  principal_transaction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  source_gross_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  source_principal_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  target_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  target_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    applied_rate: null
                    approval_ref: null
                    conversion_execution_id: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_detail: null
                    failure_reason: null
                    family: conversion
                    fee_summary: null
                    fee_transaction_ids: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    ledger_posted_target_amount: null
                    leg_attempt_id: null
                    posted_at: null
                    principal_amount:
                      currency: USD
                      value: "250.00"
                    principal_transaction_id: null
                    settled_at: null
                    source_gross_amount: null
                    source_principal_amount: null
                    status: cancelled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_amount: null
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversions.cancel
      x-required-capability:
        - conversions.manage
  /conversions/preview:
    post:
      description: Returns a non-binding ledger-native conversion preview for display.
        `economics` names source gross amount, fee summary, source principal
        amount, indicative rate, and target amount explicitly; `binding` is
        always false. Preview does not reserve funds, lock a rate, create an
        executable quote, or resolve external settlement facts.
        Creating/executing a conversion may recompute fees and rate before
        ledger posting.
      summary: Preview a conversion
      tags:
        - Live Operations
        - Conversions
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              from_amount:
                currency: USD
                value: "250.00"
              to_currency: BTC
            schema:
              required:
                - from_amount
                - to_currency
                - account_ref
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                from_amount:
                  required:
                    - value
                    - currency
                  type: object
                  additionalProperties: false
                  properties:
                    currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    value:
                      description: DecimalString
                      type: string
                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                to_currency:
                  description: Currency code (ISO-4217 or on-chain ticker)
                  type: string
                  pattern: ^[A-Z0-9]{1,16}$
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  from_amount:
                    currency: USD
                    value: "250.00"
                  to_currency: BTC
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                binding: false
                calculated_at: 2026-05-01T10:00:00Z
                economics:
                  binding: false
                  fee_summary:
                    components:
                      - amount:
                          currency: USD
                          value: "1.00"
                        kind: platform_fee
                    total:
                      currency: USD
                      value: "1.00"
                  indicative_rate: "0.00002"
                  source_gross_amount:
                    currency: USD
                    value: "250.00"
                  source_principal_amount:
                    currency: USD
                    value: "249.00"
                  target_amount:
                    currency: BTC
                    value: "0.00498000"
                execution_min_source_amount:
                  currency: USD
                  value: "25.00"
                expires_at: null
                fee_summary:
                  components:
                    - type: platform_fee
                      amount:
                        currency: USD
                        value: "1.00"
                      payee_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  total:
                    currency: USD
                    value: "1.00"
                from_amount:
                  currency: USD
                  value: "250.00"
                indicative_price:
                  computed_at: 2026-05-01T10:00:00Z
                  expires_at: null
                  price: "0.00002"
                  price_type: indicative
                  provider_hint: null
                min_source_amount:
                  currency: USD
                  value: "25.00"
                principal_amount:
                  currency: USD
                  value: "249.00"
                to_amount:
                  currency: BTC
                  value: "0.00498000"
              schema:
                required:
                  - from_amount
                  - principal_amount
                  - to_amount
                  - fee_summary
                  - indicative_price
                  - calculated_at
                  - expires_at
                  - binding
                  - economics
                  - min_source_amount
                  - execution_min_source_amount
                type: object
                additionalProperties: false
                properties:
                  binding:
                    type: boolean
                    const: false
                  calculated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  economics:
                    required:
                      - source_gross_amount
                      - fee_summary
                      - source_principal_amount
                      - indicative_rate
                      - target_amount
                      - binding
                    type: object
                    additionalProperties: false
                    properties:
                      binding:
                        type: boolean
                        const: false
                      fee_summary:
                        required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      indicative_rate:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      source_gross_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      source_principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      target_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  execution_min_source_amount:
                    anyOf:
                      - required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  expires_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  fee_summary:
                    required:
                      - components
                      - total
                    type: object
                    additionalProperties: false
                    properties:
                      components:
                        type: array
                        items:
                          required:
                            - type
                            - amount
                            - payee_ref
                          type: object
                          additionalProperties: false
                          properties:
                            type:
                              type: string
                              enum:
                                - platform_fee
                                - enterprise_fee
                                - network_fee
                                - spread
                            amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            payee_ref:
                              type: string
                              pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      total:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  from_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  indicative_price:
                    required:
                      - price
                      - price_type
                      - computed_at
                    type: object
                    additionalProperties: false
                    properties:
                      computed_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      expires_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      price:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      price_type:
                        type: string
                        const: indicative
                      provider_hint:
                        anyOf:
                          - type: string
                          - type: "null"
                  min_source_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  to_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                examples:
                  - binding: false
                    calculated_at: 2026-05-01T10:00:00Z
                    economics:
                      binding: false
                      fee_summary:
                        components:
                          - amount:
                              currency: USD
                              value: "1.00"
                            kind: platform_fee
                        total:
                          currency: USD
                          value: "1.00"
                      indicative_rate: "0.00002"
                      source_gross_amount:
                        currency: USD
                        value: "250.00"
                      source_principal_amount:
                        currency: USD
                        value: "249.00"
                      target_amount:
                        currency: BTC
                        value: "0.00498000"
                    execution_min_source_amount:
                      currency: USD
                      value: "25.00"
                    expires_at: null
                    fee_summary:
                      components:
                        - type: platform_fee
                          amount:
                            currency: USD
                            value: "1.00"
                          payee_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      total:
                        currency: USD
                        value: "1.00"
                    from_amount:
                      currency: USD
                      value: "250.00"
                    indicative_price:
                      computed_at: 2026-05-01T10:00:00Z
                      expires_at: null
                      price: "0.00002"
                      price_type: indicative
                      provider_hint: null
                    min_source_amount:
                      currency: USD
                      value: "25.00"
                    principal_amount:
                      currency: USD
                      value: "249.00"
                    to_amount:
                      currency: BTC
                      value: "0.00498000"
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: conversions.preview
  /crypto-networks:
    get:
      description: Returns the authenticated global crypto-network reference catalog
        without a capability gate. Omitting active selects active networks;
        active=true and active=false are the supported boolean query spellings,
        with false selecting inactive networks. asset filters which networks
        appear; each item still lists all supported assets on that network.
        account_ref and scope_ref are rejected here. Use
        /available-crypto-networks for an account runtime-availability snapshot
        or /eligible-crypto-networks for topology eligibility.
      summary: List crypto networks
      tags:
        - Distribution
        - Crypto Networks
      security:
        - BearerAuth: []
      parameters:
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: active
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: string
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    assets:
                      - USDC
                      - ETH
                    code: ethereum
                    display_name: Ethereum
                  - active: true
                    assets:
                      - USDC
                      - POL
                    code: polygon
                    display_name: Polygon
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - code
                        - display_name
                        - active
                        - assets
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        assets:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                        code:
                          type: string
                          minLength: 1
                        display_name:
                          type: string
                          minLength: 1
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        assets:
                          - USDC
                          - ETH
                        code: ethereum
                        display_name: Ethereum
                      - active: true
                        assets:
                          - USDC
                          - POL
                        code: polygon
                        display_name: Polygon
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: crypto_networks.list
  /deposit-instructions:
    get:
      description: Lists deposit instructions for the selected rail. Crypto
        instructions route to the custody rails backend; fiat instructions are
        delegated to `fiat-rails-service` and scoped to the supplied
        `account_ref`. On fiat resources, `fiat_routing.bank_details` carries
        the receive details a provider issues — `provider_payment_reference`
        (`required` says whether a payment without it can fail),
        `account_holder_address`, `bank_address` and `correspondent_bank` —
        always present, `null` when the provider issued none.
        `provider_payment_reference` is the provider's own reference, separate
        from the pooled ISO 11649 `reference`.
      summary: List deposit instructions
      tags:
        - Distribution
        - Deposit Instructions
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: funding_endpoint
          in: query
          required: false
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      endpoint:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      network: ethereum
                    expires_at: null
                    fiat_routing: null
                    funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail_class: crypto
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - rail_class
                        - account_ref
                        - funding_endpoint_id
                        - created_at
                        - updated_at
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        asset:
                          anyOf:
                            - description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        crypto_routing:
                          anyOf:
                            - required:
                                - asset
                                - network
                                - endpoint
                              type: object
                              additionalProperties: false
                              properties:
                                asset:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                endpoint:
                                  required:
                                    - address
                                    - memo
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    address:
                                      type: string
                                      minLength: 1
                                      maxLength: 256
                                    memo:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                network:
                                  type: string
                                  minLength: 1
                            - type: "null"
                        expires_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        fiat_routing:
                          anyOf:
                            - required:
                                - asset
                                - fiat_rail
                              type: object
                              additionalProperties: false
                              properties:
                                asset:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                bank_details:
                                  anyOf:
                                    - oneOf:
                                        - required:
                                            - scheme
                                            - iban
                                            - bic
                                            - account_holder_name
                                            - bank_name
                                            - country
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            account_holder_address:
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            account_holder_name:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            bank_address:
                                              description: Postal address of the bank that holds the account.
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            bank_name:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                - type: "null"
                                            bic:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 11
                                                - type: "null"
                                            correspondent_bank:
                                              anyOf:
                                                - required:
                                                    - name
                                                    - bic
                                                    - account_number
                                                    - address
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    name:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    account_number:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        - type: "null"
                                                    address:
                                                      anyOf:
                                                        - required:
                                                            - lines
                                                            - city
                                                            - region
                                                            - postal_code
                                                            - country
                                                          type: object
                                                          additionalProperties: false
                                                          properties:
                                                            city:
                                                              type: string
                                                              minLength: 1
                                                              maxLength: 140
                                                            country:
                                                              type: string
                                                              pattern: ^[A-Z]{2}$
                                                            lines:
                                                              type: array
                                                              items:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 140
                                                              maxItems: 4
                                                              minItems: 1
                                                            postal_code:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 32
                                                                - type: "null"
                                                            region:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 140
                                                                - type: "null"
                                                        - type: "null"
                                                    bic:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 11
                                                - type: "null"
                                            country:
                                              type: string
                                              pattern: ^[A-Z]{2}$
                                            iban:
                                              type: string
                                              minLength: 1
                                              maxLength: 34
                                            provider_payment_reference:
                                              anyOf:
                                                - required:
                                                    - value
                                                    - required
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    required:
                                                      type: boolean
                                                    value:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                - type: "null"
                                            scheme:
                                              type: string
                                              const: iban
                                        - required:
                                            - scheme
                                            - account_number
                                            - routing_codes
                                            - bic
                                            - account_holder_name
                                            - bank_name
                                            - country
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            account_holder_address:
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            account_holder_name:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            account_number:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                            account_type:
                                              description: Checking or savings. Required by some payout rails (a US domestic
                                                wire); null or absent where the
                                                rail has no such concept.
                                              anyOf:
                                                - type: string
                                                  enum:
                                                    - checking
                                                    - savings
                                                - type: "null"
                                            bank_address:
                                              description: Postal address of the bank that holds the account.
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            bank_name:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                - type: "null"
                                            bic:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 11
                                                - type: "null"
                                            correspondent_bank:
                                              anyOf:
                                                - required:
                                                    - name
                                                    - bic
                                                    - account_number
                                                    - address
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    name:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    account_number:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        - type: "null"
                                                    address:
                                                      anyOf:
                                                        - required:
                                                            - lines
                                                            - city
                                                            - region
                                                            - postal_code
                                                            - country
                                                          type: object
                                                          additionalProperties: false
                                                          properties:
                                                            city:
                                                              type: string
                                                              minLength: 1
                                                              maxLength: 140
                                                            country:
                                                              type: string
                                                              pattern: ^[A-Z]{2}$
                                                            lines:
                                                              type: array
                                                              items:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 140
                                                              maxItems: 4
                                                              minItems: 1
                                                            postal_code:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 32
                                                                - type: "null"
                                                            region:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 140
                                                                - type: "null"
                                                        - type: "null"
                                                    bic:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 11
                                                - type: "null"
                                            country:
                                              type: string
                                              pattern: ^[A-Z]{2}$
                                            provider_payment_reference:
                                              anyOf:
                                                - required:
                                                    - value
                                                    - required
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    required:
                                                      type: boolean
                                                    value:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                - type: "null"
                                            routing_codes:
                                              type: array
                                              items:
                                                required:
                                                  - type
                                                  - value
                                                type: object
                                                additionalProperties: false
                                                properties:
                                                  type:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  value:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 64
                                              maxItems: 16
                                              minItems: 1
                                            scheme:
                                              type: string
                                              const: local_account
                                    - type: "null"
                                fiat_rail:
                                  type: string
                                  enum:
                                    - sepa_credit_transfer
                                    - faster_payments
                                    - swift
                                    - local_bank_transfer
                                    - fedwire
                                reference:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        funding_endpoint_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        rail_class:
                          type: string
                          enum:
                            - fiat
                            - crypto
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        asset: USDC
                        created_at: 2026-05-01T10:00:00Z
                        crypto_routing:
                          asset: USDC
                          endpoint:
                            address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                            memo: null
                          network: ethereum
                        expires_at: null
                        fiat_routing: null
                        funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail_class: crypto
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: deposit_instructions.list
      x-required-capability:
        - deposit_instructions.read
    post:
      description: "Creates a fiat deposit instruction against the pooled fiat route
        (delegated to `fiat-rails-service`). Crypto is rejected: crypto deposit
        addresses are minted through funding-endpoint provisioning.
        `funding_endpoint_id` optionally links a previously provisioned
        endpoint; null mints a standalone instruction. This is a pooled
        payment-reference route: virtual-account routes such as an individually
        provisioned CVU refuse instruction creation with 422 and reason
        `fiat_unsupported_mode`; use the funding endpoint itself for that route.
        The pooled route owner is derived server-side and never accepted from
        the caller. The instruction carries the payment reference that makes
        pooled coordinates usable, so every request — standalone or linked to an
        endpoint — is first checked for account admission, before the route
        availability, the route owner or the endpoint mode is resolved: the
        account must not be suspended or closed; a client account needs a
        verified client and an enterprise master account a verified enterprise,
        and the enterprise behind the account (the parent of the client, or the
        owner of the master account) must be operational and unrestricted (one
        still being admitted, offboarding, terminated or restricted is refused);
        a master account owned by a platform operator is decided on its own
        status alone. A refused account returns `422` with `code =
        not_admissible`, `data.reason` one of `CLIENT_NOT_VERIFIED`,
        `ENTERPRISE_NOT_VERIFIED`, `ENTERPRISE_NOT_OPERATIONAL`,
        `ENTERPRISE_RESTRICTED`, `ACCOUNT_SUSPENDED`, `ACCOUNT_CLOSED`,
        `CLIENT_SUSPENDED`, `CLIENT_CLOSED` and `data.source` naming the check
        that refused (`verification`, `lifecycle`); when admission cannot be
        checked the request returns `503 temporarily_unavailable`. Neither
        response creates an instruction. An idempotent retry is checked again,
        so an account refused since its first request gets the refusal instead
        of the stored instruction. Idempotent on the required `Idempotency-Key`
        header; an `idempotency_key` body field is rejected. On fiat resources,
        `fiat_routing.bank_details` carries the receive details a provider
        issues — `provider_payment_reference` (`required` says whether a payment
        without it can fail), `account_holder_address`, `bank_address` and
        `correspondent_bank` — always present, `null` when the provider issued
        none. `provider_payment_reference` is the provider's own reference,
        separate from the pooled ISO 11649 `reference`."
      summary: Create deposit instruction
      tags:
        - Distribution
        - Deposit Instructions
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Client-generated key, 1-128 characters. Accepted on POST requests
            and required where marked. For the same concrete path and
            caller/subject/tenant scope, an identical body replays the original
            status and body; a different body returns 409 idempotency_conflict.
            Keep query parameters unchanged when retrying.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              funding_endpoint_id: null
              rail_class: fiat
              routing:
                asset: EUR
                fiat_rail: sepa_credit_transfer
            schema:
              required:
                - rail_class
                - account_ref
                - routing
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                funding_endpoint_id:
                  anyOf:
                    - type: string
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      format: uuid
                    - type: "null"
                rail_class:
                  type: string
                  const: fiat
                routing:
                  required:
                    - asset
                    - fiat_rail
                  type: object
                  additionalProperties: false
                  properties:
                    asset:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    bank_details:
                      anyOf:
                        - oneOf:
                            - required:
                                - scheme
                                - iban
                                - bic
                                - account_holder_name
                                - bank_name
                                - country
                              type: object
                              additionalProperties: false
                              properties:
                                account_holder_address:
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                account_holder_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                bank_address:
                                  description: Postal address of the bank that holds the account.
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                bank_name:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                                bic:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 11
                                    - type: "null"
                                correspondent_bank:
                                  anyOf:
                                    - required:
                                        - name
                                        - bic
                                        - account_number
                                        - address
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        name:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        account_number:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 64
                                            - type: "null"
                                        address:
                                          anyOf:
                                            - required:
                                                - lines
                                                - city
                                                - region
                                                - postal_code
                                                - country
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                city:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                country:
                                                  type: string
                                                  pattern: ^[A-Z]{2}$
                                                lines:
                                                  type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  maxItems: 4
                                                  minItems: 1
                                                postal_code:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 32
                                                    - type: "null"
                                                region:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    - type: "null"
                                            - type: "null"
                                        bic:
                                          type: string
                                          minLength: 1
                                          maxLength: 11
                                    - type: "null"
                                country:
                                  type: string
                                  pattern: ^[A-Z]{2}$
                                iban:
                                  type: string
                                  minLength: 1
                                  maxLength: 34
                                provider_payment_reference:
                                  anyOf:
                                    - required:
                                        - value
                                        - required
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        required:
                                          type: boolean
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                    - type: "null"
                                scheme:
                                  type: string
                                  const: iban
                            - required:
                                - scheme
                                - account_number
                                - routing_codes
                                - bic
                                - account_holder_name
                                - bank_name
                                - country
                              type: object
                              additionalProperties: false
                              properties:
                                account_holder_address:
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                account_holder_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                account_number:
                                  type: string
                                  minLength: 1
                                  maxLength: 64
                                account_type:
                                  description: Checking or savings. Required by some payout rails (a US domestic
                                    wire); null or absent where the rail has no
                                    such concept.
                                  anyOf:
                                    - type: string
                                      enum:
                                        - checking
                                        - savings
                                    - type: "null"
                                bank_address:
                                  description: Postal address of the bank that holds the account.
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                bank_name:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                                bic:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 11
                                    - type: "null"
                                correspondent_bank:
                                  anyOf:
                                    - required:
                                        - name
                                        - bic
                                        - account_number
                                        - address
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        name:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        account_number:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 64
                                            - type: "null"
                                        address:
                                          anyOf:
                                            - required:
                                                - lines
                                                - city
                                                - region
                                                - postal_code
                                                - country
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                city:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                country:
                                                  type: string
                                                  pattern: ^[A-Z]{2}$
                                                lines:
                                                  type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  maxItems: 4
                                                  minItems: 1
                                                postal_code:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 32
                                                    - type: "null"
                                                region:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    - type: "null"
                                            - type: "null"
                                        bic:
                                          type: string
                                          minLength: 1
                                          maxLength: 11
                                    - type: "null"
                                country:
                                  type: string
                                  pattern: ^[A-Z]{2}$
                                provider_payment_reference:
                                  anyOf:
                                    - required:
                                        - value
                                        - required
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        required:
                                          type: boolean
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                    - type: "null"
                                routing_codes:
                                  type: array
                                  items:
                                    required:
                                      - type
                                      - value
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      type:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      value:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                  maxItems: 16
                                  minItems: 1
                                scheme:
                                  type: string
                                  const: local_account
                        - type: "null"
                    fiat_rail:
                      type: string
                      enum:
                        - sepa_credit_transfer
                        - faster_payments
                        - swift
                        - local_bank_transfer
                        - fedwire
                    reference:
                      anyOf:
                        - type: string
                        - type: "null"
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  funding_endpoint_id: null
                  rail_class: fiat
                  routing:
                    asset: EUR
                    fiat_rail: sepa_credit_transfer
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                asset: EUR
                created_at: 2026-05-01T10:00:00Z
                crypto_routing: null
                expires_at: null
                fiat_routing:
                  asset: EUR
                  bank_details:
                    account_holder_address: null
                    account_holder_name: Example Treasury
                    bank_address: null
                    bank_name: Demo Bank
                    bic: COBADEFFXXX
                    correspondent_bank: null
                    country: DE
                    iban: DE89370400440532013000
                    provider_payment_reference: null
                    scheme: iban
                  fiat_rail: sepa_credit_transfer
                  reference: RF18539007547034
                funding_endpoint_id: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                rail_class: fiat
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - account_ref
                  - funding_endpoint_id
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - endpoint
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          endpoint:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  expires_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - asset
                          - fiat_rail
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          bank_details:
                            anyOf:
                              - oneOf:
                                  - required:
                                      - scheme
                                      - iban
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      iban:
                                        type: string
                                        minLength: 1
                                        maxLength: 34
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      scheme:
                                        type: string
                                        const: iban
                                  - required:
                                      - scheme
                                      - account_number
                                      - routing_codes
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      account_number:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      account_type:
                                        description: Checking or savings. Required by some payout rails (a US domestic
                                          wire); null or absent where the rail
                                          has no such concept.
                                        anyOf:
                                          - type: string
                                            enum:
                                              - checking
                                              - savings
                                          - type: "null"
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      routing_codes:
                                        type: array
                                        items:
                                          required:
                                            - type
                                            - value
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            type:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                            value:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                        maxItems: 16
                                        minItems: 1
                                      scheme:
                                        type: string
                                        const: local_account
                              - type: "null"
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          reference:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  funding_endpoint_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: EUR
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing: null
                    expires_at: null
                    fiat_routing:
                      asset: EUR
                      bank_details:
                        account_holder_address: null
                        account_holder_name: Example Treasury
                        bank_address: null
                        bank_name: Demo Bank
                        bic: COBADEFFXXX
                        correspondent_bank: null
                        country: DE
                        iban: DE89370400440532013000
                        provider_payment_reference: null
                        scheme: iban
                      fiat_rail: sepa_credit_transfer
                      reference: RF18539007547034
                    funding_endpoint_id: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail_class: fiat
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: deposit_instructions.create
      x-required-capability:
        - deposit_instructions.create
  /deposit-instructions/{deposit_instruction_id}:
    get:
      description: Reads a deposit instruction by id. The `rail_class` query parameter
        is required so edge can route directly to the selected backend. Fiat
        reads also require `account_ref` because fiat deposit instructions are
        account-scoped; they are delegated to `fiat-rails-service`, and unknown
        or out-of-scope fiat ids return `resource_not_found`. On fiat resources,
        `fiat_routing.bank_details` carries the receive details a provider
        issues — `provider_payment_reference` (`required` says whether a payment
        without it can fail), `account_holder_address`, `bank_address` and
        `correspondent_bank` — always present, `null` when the provider issued
        none. `provider_payment_reference` is the provider's own reference,
        separate from the pooled ISO 11649 `reference`.
      summary: Get deposit instruction
      tags:
        - Distribution
        - Deposit Instructions
      security:
        - BearerAuth: []
      parameters:
        - name: deposit_instruction_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  endpoint:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  network: ethereum
                expires_at: null
                fiat_routing: null
                funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                rail_class: crypto
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - account_ref
                  - funding_endpoint_id
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - endpoint
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          endpoint:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  expires_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - asset
                          - fiat_rail
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          bank_details:
                            anyOf:
                              - oneOf:
                                  - required:
                                      - scheme
                                      - iban
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      iban:
                                        type: string
                                        minLength: 1
                                        maxLength: 34
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      scheme:
                                        type: string
                                        const: iban
                                  - required:
                                      - scheme
                                      - account_number
                                      - routing_codes
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      account_number:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      account_type:
                                        description: Checking or savings. Required by some payout rails (a US domestic
                                          wire); null or absent where the rail
                                          has no such concept.
                                        anyOf:
                                          - type: string
                                            enum:
                                              - checking
                                              - savings
                                          - type: "null"
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      routing_codes:
                                        type: array
                                        items:
                                          required:
                                            - type
                                            - value
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            type:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                            value:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                        maxItems: 16
                                        minItems: 1
                                      scheme:
                                        type: string
                                        const: local_account
                              - type: "null"
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          reference:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  funding_endpoint_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      endpoint:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      network: ethereum
                    expires_at: null
                    fiat_routing: null
                    funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail_class: crypto
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: deposit_instructions.get
      x-required-capability:
        - deposit_instructions.read
  /deposits:
    get:
      summary: List deposits
      tags:
        - Live Operations
        - Deposits
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    admission_hold_reason: null
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    deposit_instruction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    failure_reason: null
                    family: deposit
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fee_transaction_ids:
                      - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fill_rate: null
                    funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    inbound_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail_correlation_ref: TXN-0001
                    settled_at: 2026-05-01T10:00:00Z
                    settlement_ref: SETTLE-0001
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - family
                        - status
                        - account_ref
                        - principal_amount
                        - fee_summary
                        - fill_rate
                        - failure_reason
                        - settled_at
                        - approval_ref
                        - subject_attribution
                        - created_at
                        - updated_at
                        - admission_hold_reason
                        - inbound_attempt_id
                        - rail_correlation_ref
                        - funding_endpoint_id
                        - deposit_instruction_id
                        - settlement_ref
                        - principal_transaction_id
                        - fee_transaction_ids
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        admission_hold_reason:
                          anyOf:
                            - type: string
                              enum:
                                - CLIENT_NOT_VERIFIED
                                - ENTERPRISE_NOT_VERIFIED
                                - ENTERPRISE_NOT_OPERATIONAL
                                - ENTERPRISE_RESTRICTED
                                - ACCOUNT_SUSPENDED
                                - ACCOUNT_CLOSED
                                - CLIENT_SUSPENDED
                                - CLIENT_CLOSED
                            - type: "null"
                        approval_ref:
                          anyOf:
                            - required:
                                - approval_id
                                - reason_code
                                - expires_at
                              type: object
                              additionalProperties: false
                              properties:
                                approval_id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                expires_at:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                reason_code:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        compliance_assessment_ref:
                          anyOf:
                            - type: string
                              pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        deposit_instruction_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        failure_reason:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        family:
                          type: string
                          const: deposit
                        fee_summary:
                          anyOf:
                            - required:
                                - components
                                - total
                              type: object
                              additionalProperties: false
                              properties:
                                components:
                                  type: array
                                  items:
                                    required:
                                      - kind
                                      - amount
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      amount:
                                        required:
                                          - value
                                          - currency
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          currency:
                                            description: Currency code (ISO-4217 or on-chain ticker)
                                            type: string
                                            pattern: ^[A-Z0-9]{1,16}$
                                          value:
                                            description: DecimalString
                                            type: string
                                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                      kind:
                                        type: string
                                        enum:
                                          - platform_fee
                                          - enterprise_fee
                                          - network_fee
                                          - spread
                                total:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        fee_transaction_ids:
                          anyOf:
                            - type: array
                              items:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                            - type: "null"
                        fill_rate:
                          anyOf:
                            - type: string
                            - type: "null"
                        funding_endpoint_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        inbound_attempt_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        principal_amount:
                          required:
                            - value
                            - currency
                          type: object
                          additionalProperties: false
                          properties:
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            value:
                              description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        principal_transaction_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        rail_correlation_ref:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        settled_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        settlement_ref:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        status:
                          type: string
                          enum:
                            - requested
                            - admissible
                            - executing
                            - pending_approval
                            - pending_admission
                            - pending_compliance
                            - executed
                            - settled
                            - ledger_visible
                            - failed
                            - cancelled
                            - partially_settled
                        subject_attribution:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                            - federation
                            - enterprise_binding
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            authenticated_principal:
                              required:
                                - id
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                tenant_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            enterprise_binding:
                              required:
                                - topology_ref
                                - tenant_type
                              type: object
                              additionalProperties: false
                              properties:
                                tenant_type:
                                  type: string
                                  enum:
                                    - enterprise
                                    - platform_operator
                                topology_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            federation:
                              anyOf:
                                - required:
                                    - issuer
                                    - external_subject
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    external_subject:
                                      type: string
                                      minLength: 1
                                    issuer:
                                      type: string
                                      minLength: 1
                                - type: "null"
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                        updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        admission_hold_reason: null
                        approval_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        deposit_instruction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        failure_reason: null
                        family: deposit
                        fee_summary:
                          components:
                            - amount:
                                currency: USDC
                                value: "1.00"
                              kind: network_fee
                          total:
                            currency: USDC
                            value: "1.00"
                        fee_transaction_ids:
                          - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        fill_rate: null
                        funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        inbound_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_amount:
                          currency: USDC
                          value: "250.00"
                        principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail_correlation_ref: TXN-0001
                        settled_at: 2026-05-01T10:00:00Z
                        settlement_ref: SETTLE-0001
                        status: settled
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: deposits.list
      x-required-capability:
        - deposits.read
  /deposits/{deposit_id}:
    get:
      summary: Get deposit
      tags:
        - Live Operations
        - Deposits
      security:
        - BearerAuth: []
      parameters:
        - name: deposit_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                admission_hold_reason: null
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                deposit_instruction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                failure_reason: null
                family: deposit
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: network_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fee_transaction_ids:
                  - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                fill_rate: null
                funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                inbound_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                rail_correlation_ref: TXN-0001
                settled_at: 2026-05-01T10:00:00Z
                settlement_ref: SETTLE-0001
                status: settled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - admission_hold_reason
                  - inbound_attempt_id
                  - rail_correlation_ref
                  - funding_endpoint_id
                  - deposit_instruction_id
                  - settlement_ref
                  - principal_transaction_id
                  - fee_transaction_ids
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  deposit_instruction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: deposit
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fee_transaction_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  funding_endpoint_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  inbound_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  principal_transaction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  rail_correlation_ref:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  settlement_ref:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    admission_hold_reason: null
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    deposit_instruction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    failure_reason: null
                    family: deposit
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fee_transaction_ids:
                      - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fill_rate: null
                    funding_endpoint_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    inbound_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    principal_transaction_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail_correlation_ref: TXN-0001
                    settled_at: 2026-05-01T10:00:00Z
                    settlement_ref: SETTLE-0001
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: deposits.get
      x-required-capability:
        - deposits.read
  /eligible-crypto-networks:
    get:
      description: Returns active crypto networks projected from eligible asset/rail
        tuples for an enterprise or client scope. direction defaults to deposit
        and also accepts withdrawal. When asset is supplied, each item contains
        only assets that passed that filter and eligibility check. The caller
        must have an enterprise tenant binding covering scope_ref;
        platform-operator and unbound callers receive 403, while a scope outside
        the tenant receives 404. Use /available-crypto-networks for an
        operating-account runtime-availability snapshot.
      summary: List eligible crypto networks
      tags:
        - Distribution
        - Crypto Networks
      security:
        - BearerAuth: []
      parameters:
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - deposit
              - withdrawal
            default: deposit
        - name: scope_ref
          in: query
          required: true
          schema:
            anyOf:
              - type: string
                pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              - type: string
                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    assets:
                      - USDC
                    code: ethereum
                    display_name: Ethereum
                  - active: true
                    assets:
                      - USDC
                    code: polygon
                    display_name: Polygon
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - code
                        - display_name
                        - active
                        - assets
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        assets:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                        code:
                          type: string
                          minLength: 1
                        display_name:
                          type: string
                          minLength: 1
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        assets:
                          - USDC
                        code: ethereum
                        display_name: Ethereum
                      - active: true
                        assets:
                          - USDC
                        code: polygon
                        display_name: Polygon
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: eligible_crypto_networks.list
  /eligible-payout-methods:
    get:
      description: Returns fiat withdrawal methods eligible for the supplied
        enterprise or client `scope_ref`, based on technical, commercial and
        feature-flag eligibility. The scope must lie within the caller’s bound
        enterprise or client scope; an out-of-scope target returns `404
        resource_not_found`, and an unbound or platform-bound caller is refused.
        Eligibility does not establish account-level runtime readiness or
        guarantee execution. Use `/payout-methods` for the global reference
        catalog.
      summary: List eligible payout methods
      tags:
        - Distribution
        - Payout Methods
      security:
        - BearerAuth: []
      parameters:
        - name: rail
          in: query
          required: false
          schema:
            type: string
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: scope_ref
          in: query
          required: true
          schema:
            anyOf:
              - type: string
                pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              - type: string
                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    code: sepa_credit_transfer
                    currencies:
                      - EUR
                    display_name: SEPA
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail: sepa_credit_transfer
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - code
                        - display_name
                        - rail
                        - currencies
                        - active
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        code:
                          type: string
                          pattern: ^[a-z0-9_]+$
                        currencies:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          minItems: 1
                        display_name:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        code: sepa_credit_transfer
                        currencies:
                          - EUR
                        display_name: SEPA
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail: sepa_credit_transfer
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: eligible_payout_methods.list
  /enterprise-commercial-agreements:
    get:
      description: Lists versions for one enterprise and one client scope.
        client_scope defaults to all_clients, which selects only the
        enterprise-wide agreement series; it does not include every
        single-client series. single_client requires client_ref belonging to
        that enterprise. service_type filters bindings; page_size defaults to
        100 (maximum 200).
      summary: List commercial agreement versions
      tags:
        - Setup
        - Commercial Agreements
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: client_scope
          in: query
          required: false
          schema:
            type: string
            enum:
              - all_clients
              - single_client
        - name: client_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: service_type
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - custody
                  - conversion
                  - withdrawal_crypto
                  - withdrawal_fiat
                  - deposit_crypto
                  - deposit_fiat
                  - internal_transfer
                  - staking
              - type: "null"
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/PageSize"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                page:
                  items:
                    - client_scope:
                        kind: all_clients
                      created_at: 2026-05-01T10:00:00Z
                      effective_from: 2026-05-01T10:00:00Z
                      effective_to: null
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      metadata: null
                      service_bindings:
                        - fee_schedule:
                            bps: 25
                            model: bps
                          service_type: conversion
                      status: active
                      version: 1
                  next_page_token: null
              schema:
                required:
                  - page
                type: object
                additionalProperties: false
                properties:
                  page:
                    required:
                      - items
                      - next_page_token
                    type: object
                    additionalProperties: false
                    properties:
                      items:
                        type: array
                        items:
                          required:
                            - id
                            - enterprise_ref
                            - client_scope
                            - version
                            - status
                            - effective_from
                            - effective_to
                            - service_bindings
                            - created_at
                          type: object
                          additionalProperties: false
                          properties:
                            client_scope:
                              anyOf:
                                - required:
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    kind:
                                      type: string
                                      const: all_clients
                                - required:
                                    - kind
                                    - client_ref
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    client_ref:
                                      type: string
                                      pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    kind:
                                      type: string
                                      const: single_client
                            created_at:
                              type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            effective_from:
                              type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            effective_to:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: "null"
                            enterprise_ref:
                              type: string
                              pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            metadata:
                              anyOf:
                                - type: object
                                  additionalProperties: {}
                                  propertyNames:
                                    type: string
                                - type: "null"
                            service_bindings:
                              type: array
                              items:
                                required:
                                  - service_type
                                  - fee_schedule
                                type: object
                                additionalProperties: false
                                properties:
                                  fee_schedule:
                                    required:
                                      - model
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      minimum:
                                        anyOf:
                                          - required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          - type: "null"
                                      maximum:
                                        anyOf:
                                          - required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          - type: "null"
                                      bps:
                                        anyOf:
                                          - type: integer
                                            minimum: 0
                                            maximum: 9007199254740991
                                          - type: "null"
                                      fixed:
                                        anyOf:
                                          - required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          - type: "null"
                                      metadata:
                                        anyOf:
                                          - type: object
                                            additionalProperties: {}
                                            propertyNames:
                                              type: string
                                          - type: "null"
                                      model:
                                        type: string
                                        enum:
                                          - fixed
                                          - bps
                                          - fixed_plus_bps
                                          - tiered
                                      rounding_mode:
                                        anyOf:
                                          - type: string
                                            enum:
                                              - half_up
                                              - up
                                              - down
                                          - type: "null"
                                      tiers:
                                        anyOf:
                                          - type: array
                                            items:
                                              required:
                                                - up_to_amount
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                bps:
                                                  anyOf:
                                                    - type: integer
                                                      minimum: 0
                                                      maximum: 9007199254740991
                                                    - type: "null"
                                                fixed:
                                                  anyOf:
                                                    - required:
                                                        - value
                                                        - currency
                                                      type: object
                                                      additionalProperties: false
                                                      properties:
                                                        currency:
                                                          description: Currency code (ISO-4217 or on-chain ticker)
                                                          type: string
                                                          pattern: ^[A-Z0-9]{1,16}$
                                                        value:
                                                          description: DecimalString
                                                          type: string
                                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                                    - type: "null"
                                                up_to_amount:
                                                  anyOf:
                                                    - description: DecimalString
                                                      type: string
                                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                                    - type: "null"
                                          - type: "null"
                                  service_type:
                                    type: string
                                    enum:
                                      - custody
                                      - conversion
                                      - withdrawal_crypto
                                      - withdrawal_fiat
                                      - deposit_crypto
                                      - deposit_fiat
                                      - internal_transfer
                                      - staking
                            status:
                              type: string
                              enum:
                                - draft
                                - active
                                - superseded
                            version:
                              type: integer
                              maximum: 9007199254740991
                              exclusiveMinimum: 0
                      next_page_token:
                        anyOf:
                          - type: string
                          - type: "null"
                examples:
                  - page:
                      items:
                        - client_scope:
                            kind: all_clients
                          created_at: 2026-05-01T10:00:00Z
                          effective_from: 2026-05-01T10:00:00Z
                          effective_to: null
                          enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          metadata: null
                          service_bindings:
                            - fee_schedule:
                                bps: 25
                                model: bps
                              service_type: conversion
                          status: active
                          version: 1
                      next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprise_commercial_agreements.list
      x-required-capability:
        - commercial_agreements.read
    post:
      description: Creates an active version for the enterprise/client scope.
        effective_from must not precede the latest version. A new version
        supersedes the current active version at effective_from. An existing
        version with the same scope and effective_from is returned unchanged,
        even if the submitted bindings differ. At least one service binding is
        required; fee amounts use value and currency.
      summary: Create commercial agreement version
      tags:
        - Setup
        - Commercial Agreements
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              client_scope:
                kind: all_clients
              effective_from: 2026-05-01T10:00:00Z
              enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              metadata: null
              service_bindings:
                - fee_schedule:
                    bps: 25
                    model: bps
                  service_type: conversion
            schema:
              required:
                - enterprise_ref
                - client_scope
                - effective_from
                - service_bindings
              type: object
              additionalProperties: false
              properties:
                client_scope:
                  anyOf:
                    - required:
                        - kind
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: all_clients
                    - required:
                        - kind
                        - client_ref
                      type: object
                      additionalProperties: false
                      properties:
                        client_ref:
                          type: string
                          pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        kind:
                          type: string
                          const: single_client
                effective_from:
                  type: string
                  format: date-time
                enterprise_ref:
                  type: string
                  pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                metadata:
                  anyOf:
                    - type: object
                      additionalProperties: {}
                      propertyNames:
                        type: string
                    - type: "null"
                service_bindings:
                  type: array
                  items:
                    required:
                      - service_type
                      - fee_schedule
                    type: object
                    additionalProperties: false
                    properties:
                      fee_schedule:
                        required:
                          - model
                        type: object
                        additionalProperties: false
                        properties:
                          minimum:
                            anyOf:
                              - required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                              - type: "null"
                          maximum:
                            anyOf:
                              - required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                              - type: "null"
                          bps:
                            anyOf:
                              - type: integer
                                minimum: 0
                                maximum: 9007199254740991
                              - type: "null"
                          fixed:
                            anyOf:
                              - required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                              - type: "null"
                          metadata:
                            anyOf:
                              - type: object
                                additionalProperties: {}
                                propertyNames:
                                  type: string
                              - type: "null"
                          model:
                            type: string
                            enum:
                              - fixed
                              - bps
                              - fixed_plus_bps
                              - tiered
                          rounding_mode:
                            anyOf:
                              - type: string
                                enum:
                                  - half_up
                                  - up
                                  - down
                              - type: "null"
                          tiers:
                            anyOf:
                              - type: array
                                items:
                                  required:
                                    - up_to_amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    bps:
                                      anyOf:
                                        - type: integer
                                          minimum: 0
                                          maximum: 9007199254740991
                                        - type: "null"
                                    fixed:
                                      anyOf:
                                        - required:
                                            - value
                                            - currency
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            currency:
                                              description: Currency code (ISO-4217 or on-chain ticker)
                                              type: string
                                              pattern: ^[A-Z0-9]{1,16}$
                                            value:
                                              description: DecimalString
                                              type: string
                                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                        - type: "null"
                                    up_to_amount:
                                      anyOf:
                                        - description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                        - type: "null"
                              - type: "null"
                      service_type:
                        type: string
                        enum:
                          - custody
                          - conversion
                          - withdrawal_crypto
                          - withdrawal_fiat
                          - deposit_crypto
                          - deposit_fiat
                          - internal_transfer
                          - staking
                  minItems: 1
              examples:
                - client_scope:
                    kind: all_clients
                  effective_from: 2026-05-01T10:00:00Z
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  metadata: null
                  service_bindings:
                    - fee_schedule:
                        bps: 25
                        model: bps
                      service_type: conversion
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                agreement:
                  client_scope:
                    kind: all_clients
                  created_at: 2026-05-01T10:00:00Z
                  effective_from: 2026-05-01T10:00:00Z
                  effective_to: null
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  metadata: null
                  service_bindings:
                    - fee_schedule:
                        bps: 25
                        model: bps
                      service_type: conversion
                  status: active
                  version: 1
              schema:
                required:
                  - agreement
                type: object
                additionalProperties: false
                properties:
                  agreement:
                    required:
                      - id
                      - enterprise_ref
                      - client_scope
                      - version
                      - status
                      - effective_from
                      - effective_to
                      - service_bindings
                      - created_at
                    type: object
                    additionalProperties: false
                    properties:
                      client_scope:
                        anyOf:
                          - required:
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                const: all_clients
                          - required:
                              - kind
                              - client_ref
                            type: object
                            additionalProperties: false
                            properties:
                              client_ref:
                                type: string
                                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              kind:
                                type: string
                                const: single_client
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      effective_from:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      effective_to:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      enterprise_ref:
                        type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      metadata:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                            propertyNames:
                              type: string
                          - type: "null"
                      service_bindings:
                        type: array
                        items:
                          required:
                            - service_type
                            - fee_schedule
                          type: object
                          additionalProperties: false
                          properties:
                            fee_schedule:
                              required:
                                - model
                              type: object
                              additionalProperties: false
                              properties:
                                minimum:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                maximum:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                bps:
                                  anyOf:
                                    - type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                    - type: "null"
                                fixed:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                metadata:
                                  anyOf:
                                    - type: object
                                      additionalProperties: {}
                                      propertyNames:
                                        type: string
                                    - type: "null"
                                model:
                                  type: string
                                  enum:
                                    - fixed
                                    - bps
                                    - fixed_plus_bps
                                    - tiered
                                rounding_mode:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - half_up
                                        - up
                                        - down
                                    - type: "null"
                                tiers:
                                  anyOf:
                                    - type: array
                                      items:
                                        required:
                                          - up_to_amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          bps:
                                            anyOf:
                                              - type: integer
                                                minimum: 0
                                                maximum: 9007199254740991
                                              - type: "null"
                                          fixed:
                                            anyOf:
                                              - required:
                                                  - value
                                                  - currency
                                                type: object
                                                additionalProperties: false
                                                properties:
                                                  currency:
                                                    description: Currency code (ISO-4217 or on-chain ticker)
                                                    type: string
                                                    pattern: ^[A-Z0-9]{1,16}$
                                                  value:
                                                    description: DecimalString
                                                    type: string
                                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                              - type: "null"
                                          up_to_amount:
                                            anyOf:
                                              - description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                              - type: "null"
                                    - type: "null"
                            service_type:
                              type: string
                              enum:
                                - custody
                                - conversion
                                - withdrawal_crypto
                                - withdrawal_fiat
                                - deposit_crypto
                                - deposit_fiat
                                - internal_transfer
                                - staking
                      status:
                        type: string
                        enum:
                          - draft
                          - active
                          - superseded
                      version:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                examples:
                  - agreement:
                      client_scope:
                        kind: all_clients
                      created_at: 2026-05-01T10:00:00Z
                      effective_from: 2026-05-01T10:00:00Z
                      effective_to: null
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      metadata: null
                      service_bindings:
                        - fee_schedule:
                            bps: 25
                            model: bps
                          service_type: conversion
                      status: active
                      version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprise_commercial_agreements.create
      x-required-capability:
        - commercial_agreements.create
  /enterprise-commercial-agreements/{agreement_id}:
    get:
      summary: Get commercial agreement version
      tags:
        - Setup
        - Commercial Agreements
      security:
        - BearerAuth: []
      parameters:
        - name: agreement_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                agreement:
                  client_scope:
                    kind: all_clients
                  created_at: 2026-05-01T10:00:00Z
                  effective_from: 2026-05-01T10:00:00Z
                  effective_to: null
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  metadata: null
                  service_bindings:
                    - fee_schedule:
                        bps: 25
                        model: bps
                      service_type: conversion
                  status: active
                  version: 1
              schema:
                required:
                  - agreement
                type: object
                additionalProperties: false
                properties:
                  agreement:
                    required:
                      - id
                      - enterprise_ref
                      - client_scope
                      - version
                      - status
                      - effective_from
                      - effective_to
                      - service_bindings
                      - created_at
                    type: object
                    additionalProperties: false
                    properties:
                      client_scope:
                        anyOf:
                          - required:
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                const: all_clients
                          - required:
                              - kind
                              - client_ref
                            type: object
                            additionalProperties: false
                            properties:
                              client_ref:
                                type: string
                                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              kind:
                                type: string
                                const: single_client
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      effective_from:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      effective_to:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      enterprise_ref:
                        type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      metadata:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                            propertyNames:
                              type: string
                          - type: "null"
                      service_bindings:
                        type: array
                        items:
                          required:
                            - service_type
                            - fee_schedule
                          type: object
                          additionalProperties: false
                          properties:
                            fee_schedule:
                              required:
                                - model
                              type: object
                              additionalProperties: false
                              properties:
                                minimum:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                maximum:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                bps:
                                  anyOf:
                                    - type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                    - type: "null"
                                fixed:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                metadata:
                                  anyOf:
                                    - type: object
                                      additionalProperties: {}
                                      propertyNames:
                                        type: string
                                    - type: "null"
                                model:
                                  type: string
                                  enum:
                                    - fixed
                                    - bps
                                    - fixed_plus_bps
                                    - tiered
                                rounding_mode:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - half_up
                                        - up
                                        - down
                                    - type: "null"
                                tiers:
                                  anyOf:
                                    - type: array
                                      items:
                                        required:
                                          - up_to_amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          bps:
                                            anyOf:
                                              - type: integer
                                                minimum: 0
                                                maximum: 9007199254740991
                                              - type: "null"
                                          fixed:
                                            anyOf:
                                              - required:
                                                  - value
                                                  - currency
                                                type: object
                                                additionalProperties: false
                                                properties:
                                                  currency:
                                                    description: Currency code (ISO-4217 or on-chain ticker)
                                                    type: string
                                                    pattern: ^[A-Z0-9]{1,16}$
                                                  value:
                                                    description: DecimalString
                                                    type: string
                                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                              - type: "null"
                                          up_to_amount:
                                            anyOf:
                                              - description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                              - type: "null"
                                    - type: "null"
                            service_type:
                              type: string
                              enum:
                                - custody
                                - conversion
                                - withdrawal_crypto
                                - withdrawal_fiat
                                - deposit_crypto
                                - deposit_fiat
                                - internal_transfer
                                - staking
                      status:
                        type: string
                        enum:
                          - draft
                          - active
                          - superseded
                      version:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                examples:
                  - agreement:
                      client_scope:
                        kind: all_clients
                      created_at: 2026-05-01T10:00:00Z
                      effective_from: 2026-05-01T10:00:00Z
                      effective_to: null
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      metadata: null
                      service_bindings:
                        - fee_schedule:
                            bps: 25
                            model: bps
                          service_type: conversion
                      status: active
                      version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprise_commercial_agreements.get
      x-required-capability:
        - commercial_agreements.read
  /enterprise-commercial-agreements/{agreement_id}/supersede:
    post:
      description: Closes an agreement version by setting status to superseded and
        effective_to. Requires commercial_agreements.manage and read access
        because the controller reads the current agreement first. effective_to
        must not precede effective_from or be more than five minutes in the
        past. An already closed version returns 409.
      summary: Supersede commercial agreement version
      tags:
        - Setup
        - Commercial Agreements
      security:
        - BearerAuth: []
      parameters:
        - name: agreement_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              effective_to: 2026-05-01T10:00:00Z
            schema:
              required:
                - effective_to
              type: object
              additionalProperties: false
              properties:
                effective_to:
                  type: string
                  format: date-time
              examples:
                - effective_to: 2026-05-01T10:00:00Z
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                agreement:
                  client_scope:
                    kind: all_clients
                  created_at: 2026-05-01T10:00:00Z
                  effective_from: 2026-05-01T10:00:00Z
                  effective_to: 2026-05-01T10:00:00Z
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  metadata: null
                  service_bindings:
                    - fee_schedule:
                        bps: 25
                        model: bps
                      service_type: conversion
                  status: superseded
                  version: 1
              schema:
                required:
                  - agreement
                type: object
                additionalProperties: false
                properties:
                  agreement:
                    required:
                      - id
                      - enterprise_ref
                      - client_scope
                      - version
                      - status
                      - effective_from
                      - effective_to
                      - service_bindings
                      - created_at
                    type: object
                    additionalProperties: false
                    properties:
                      client_scope:
                        anyOf:
                          - required:
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                const: all_clients
                          - required:
                              - kind
                              - client_ref
                            type: object
                            additionalProperties: false
                            properties:
                              client_ref:
                                type: string
                                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              kind:
                                type: string
                                const: single_client
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      effective_from:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      effective_to:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      enterprise_ref:
                        type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      metadata:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                            propertyNames:
                              type: string
                          - type: "null"
                      service_bindings:
                        type: array
                        items:
                          required:
                            - service_type
                            - fee_schedule
                          type: object
                          additionalProperties: false
                          properties:
                            fee_schedule:
                              required:
                                - model
                              type: object
                              additionalProperties: false
                              properties:
                                minimum:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                maximum:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                bps:
                                  anyOf:
                                    - type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                    - type: "null"
                                fixed:
                                  anyOf:
                                    - required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    - type: "null"
                                metadata:
                                  anyOf:
                                    - type: object
                                      additionalProperties: {}
                                      propertyNames:
                                        type: string
                                    - type: "null"
                                model:
                                  type: string
                                  enum:
                                    - fixed
                                    - bps
                                    - fixed_plus_bps
                                    - tiered
                                rounding_mode:
                                  anyOf:
                                    - type: string
                                      enum:
                                        - half_up
                                        - up
                                        - down
                                    - type: "null"
                                tiers:
                                  anyOf:
                                    - type: array
                                      items:
                                        required:
                                          - up_to_amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          bps:
                                            anyOf:
                                              - type: integer
                                                minimum: 0
                                                maximum: 9007199254740991
                                              - type: "null"
                                          fixed:
                                            anyOf:
                                              - required:
                                                  - value
                                                  - currency
                                                type: object
                                                additionalProperties: false
                                                properties:
                                                  currency:
                                                    description: Currency code (ISO-4217 or on-chain ticker)
                                                    type: string
                                                    pattern: ^[A-Z0-9]{1,16}$
                                                  value:
                                                    description: DecimalString
                                                    type: string
                                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                              - type: "null"
                                          up_to_amount:
                                            anyOf:
                                              - description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                              - type: "null"
                                    - type: "null"
                            service_type:
                              type: string
                              enum:
                                - custody
                                - conversion
                                - withdrawal_crypto
                                - withdrawal_fiat
                                - deposit_crypto
                                - deposit_fiat
                                - internal_transfer
                                - staking
                      status:
                        type: string
                        enum:
                          - draft
                          - active
                          - superseded
                      version:
                        type: integer
                        maximum: 9007199254740991
                        exclusiveMinimum: 0
                examples:
                  - agreement:
                      client_scope:
                        kind: all_clients
                      created_at: 2026-05-01T10:00:00Z
                      effective_from: 2026-05-01T10:00:00Z
                      effective_to: 2026-05-01T10:00:00Z
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      metadata: null
                      service_bindings:
                        - fee_schedule:
                            bps: 25
                            model: bps
                          service_type: conversion
                      status: superseded
                      version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprise_commercial_agreements.supersede
      x-required-capability:
        - commercial_agreements.manage
  /enterprises:
    get:
      description: Lists enterprises under an `enterprise_wildcard` grant anchored at
        `platform-operators/<id>` for `enterprises.list`. Holding the capability
        on a narrower scope is insufficient and returns `403
        forbidden_capability_scope`. Each row includes `first_access_method` and
        `iam_hosting`; both are null when the onboarding record is absent or
        unavailable. Only platform staff can list, so rows always carry
        `kyc_source`, `kyb_source` and `kyb_state_reason`.
      summary: List enterprises
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - name: admission_state
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - admission_review
                  - admitted
                  - operational
                  - restricted
                  - offboarding
                  - terminated
              - type: array
                items:
                  type: string
                  enum:
                    - admission_review
                    - admitted
                    - operational
                    - restricted
                    - offboarding
                    - terminated
        - name: restriction_state
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - none
                  - restricted
              - type: array
                items:
                  type: string
                  enum:
                    - none
                    - restricted
        - name: restriction_kind
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - restricted
                  - suspended
              - type: array
                items:
                  type: string
                  enum:
                    - restricted
                    - suspended
        - name: jurisdiction
          in: query
          description: Country of registration, ISO 3166-1 alpha-2.
          required: false
          schema:
            anyOf:
              - type: string
                minLength: 2
                maxLength: 2
              - type: array
                items:
                  type: string
                  minLength: 2
                  maxLength: 2
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - admission_state: operational
                    created_at: 2026-05-01T10:00:00Z
                    default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 2026-05-01T10:00:00.000Z
                    external_id: ent-ext-0001
                    first_access_method: enterprise_idp
                    iam_hosting: platform
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    jurisdiction: DE
                    jurisdiction_selected: true
                    kyb_source: sumsub
                    kyb_stage: verified
                    kyb_state: verified
                    kyb_state_reason: null
                    kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                    kyc_source: null
                    kyc_stage: null
                    legal_form: GmbH
                    legal_name: Acme Fintech GmbH
                    metadata:
                      hq_country: DE
                      industry: fintech
                    resource: enterprise
                    restriction_kind: null
                    restriction_reason: null
                    restriction_state: none
                    terminated_at: null
                    termination_reason: null
                    updated_at: 2026-05-01T10:00:00.000Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - admission_state
                        - restriction_state
                        - legal_name
                        - jurisdiction
                        - jurisdiction_selected
                        - legal_form
                        - kyc_stage
                        - kyb_stage
                        - kyb_state
                        - kyb_state_updated_at
                        - restriction_reason
                        - restriction_kind
                        - terminated_at
                        - termination_reason
                        - created_at
                        - updated_at
                        - etag
                        - first_access_method
                        - iam_hosting
                      type: object
                      additionalProperties: false
                      properties:
                        admission_state:
                          type: string
                          enum:
                            - admission_review
                            - admitted
                            - operational
                            - restricted
                            - offboarding
                            - terminated
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        default_master_account:
                          anyOf:
                            - type: string
                              pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        etag:
                          type: string
                          minLength: 1
                        external_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        first_access_method:
                          anyOf:
                            - type: string
                              enum:
                                - magic_link
                                - passkey_enrolment
                                - enterprise_idp
                            - type: "null"
                        iam_hosting:
                          anyOf:
                            - type: string
                              enum:
                                - enterprise
                                - platform
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        jurisdiction:
                          description: Country of registration, ISO 3166-1 alpha-2.
                          type: string
                          pattern: ^[A-Z]{2}$
                          minLength: 2
                          maxLength: 2
                        jurisdiction_selected:
                          type: boolean
                        kyb_source:
                          description: Present only for callers with platform-wide `enterprises.read`
                            authority; omitted for tenant callers.
                          anyOf:
                            - type: string
                              enum:
                                - bootstrap
                                - sumsub
                            - type: "null"
                        kyb_stage:
                          anyOf:
                            - type: string
                              enum:
                                - form_k_ready
                                - verified
                            - type: "null"
                        kyb_state:
                          anyOf:
                            - type: string
                              enum:
                                - not_started
                                - in_progress
                                - submitted
                                - in_review
                                - resubmission_required
                                - form_k_ready
                                - verified
                                - rejected
                            - type: "null"
                        kyb_state_reason:
                          description: Present only for callers with platform-wide `enterprises.read`
                            authority; omitted for tenant callers.
                          anyOf:
                            - type: string
                            - type: "null"
                        kyb_state_updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        kyc_source:
                          description: Present only for callers with platform-wide `enterprises.read`
                            authority; omitted for tenant callers.
                          anyOf:
                            - type: string
                              enum:
                                - bootstrap
                                - sumsub
                            - type: "null"
                        kyc_stage:
                          anyOf:
                            - type: string
                              enum:
                                - verified
                            - type: "null"
                        legal_form:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        legal_name:
                          type: string
                          minLength: 1
                        metadata:
                          anyOf:
                            - type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            - type: "null"
                        resource:
                          type: string
                          const: enterprise
                        restriction_kind:
                          anyOf:
                            - type: string
                              enum:
                                - restricted
                                - suspended
                            - type: "null"
                        restriction_reason:
                          anyOf:
                            - type: string
                            - type: "null"
                        restriction_state:
                          type: string
                          enum:
                            - none
                            - restricted
                        terminated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        termination_reason:
                          anyOf:
                            - type: string
                            - type: "null"
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - admission_state: operational
                        created_at: 2026-05-01T10:00:00Z
                        default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        etag: 2026-05-01T10:00:00.000Z
                        external_id: ent-ext-0001
                        first_access_method: enterprise_idp
                        iam_hosting: platform
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        jurisdiction: DE
                        jurisdiction_selected: true
                        kyb_source: sumsub
                        kyb_stage: verified
                        kyb_state: verified
                        kyb_state_reason: null
                        kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                        kyc_source: null
                        kyc_stage: null
                        legal_form: GmbH
                        legal_name: Acme Fintech GmbH
                        metadata:
                          hq_country: DE
                          industry: fintech
                        resource: enterprise
                        restriction_kind: null
                        restriction_reason: null
                        restriction_state: none
                        terminated_at: null
                        termination_reason: null
                        updated_at: 2026-05-01T10:00:00.000Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.list
      x-required-capability:
        - enterprises.list
    post:
      description: Creates the enterprise perimeter and its default master account.
        Requires a platform-operator binding and an `enterprise_wildcard` grant
        anchored at `platform-operators/<id>` for `enterprises.create`;
        otherwise returns `403 forbidden_capability_scope`. Admission does not
        provision the designated administrator, identity access, roles, or
        commercial agreements. Call `POST
        /enterprises/{enterprise_id}/provision` separately to complete that
        setup.
      summary: Admit enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              designated_admin:
                display_name: Acme Admin
                email: admin@acme.example
              external_id: ent-ext-0001
              jurisdiction: DE
              legal_name: Acme Fintech GmbH
              metadata:
                industry: fintech
            schema:
              required:
                - legal_name
                - jurisdiction
                - designated_admin
              type: object
              additionalProperties: false
              properties:
                designated_admin:
                  required:
                    - email
                  type: object
                  additionalProperties: false
                  properties:
                    display_name:
                      anyOf:
                        - type: string
                        - type: "null"
                    email:
                      type: string
                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                      format: email
                external_id:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: "null"
                jurisdiction:
                  description: Country of registration, ISO 3166-1 alpha-2.
                  type: string
                  pattern: ^[A-Z]{2}$
                  minLength: 2
                  maxLength: 2
                legal_name:
                  type: string
                  minLength: 1
                metadata:
                  anyOf:
                    - type: object
                      additionalProperties: {}
                      propertyNames:
                        type: string
                    - type: "null"
              examples:
                - designated_admin:
                    display_name: Acme Admin
                    email: admin@acme.example
                  external_id: ent-ext-0001
                  jurisdiction: DE
                  legal_name: Acme Fintech GmbH
                  metadata:
                    industry: fintech
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                enterprise:
                  admission_state: admitted
                  created_at: 2026-05-01T10:00:00Z
                  default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  etag: 2026-05-01T10:00:00.000Z
                  external_id: ent-ext-0001
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  jurisdiction: DE
                  jurisdiction_selected: false
                  kyb_source: null
                  kyb_stage: null
                  kyb_state: null
                  kyb_state_reason: null
                  kyb_state_updated_at: null
                  kyc_source: null
                  kyc_stage: null
                  legal_form: null
                  legal_name: Acme Fintech GmbH
                  metadata:
                    hq_country: DE
                    industry: fintech
                  resource: enterprise
                  restriction_kind: null
                  restriction_reason: null
                  restriction_state: none
                  terminated_at: null
                  termination_reason: null
                  updated_at: 2026-05-01T10:00:00.000Z
                master_account:
                  created_at: 2026-05-01T10:00:00Z
                  display_name: Acme Fintech GmbH
                  etag: 2026-05-01T10:00:00.000Z
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  parent: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  resource: master_account
                  status: active
                  tenant_type: enterprise
                  updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - enterprise
                  - master_account
                type: object
                additionalProperties: false
                properties:
                  enterprise:
                    required:
                      - id
                      - resource
                      - admission_state
                      - restriction_state
                      - legal_name
                      - jurisdiction
                      - jurisdiction_selected
                      - legal_form
                      - kyc_stage
                      - kyc_source
                      - kyb_stage
                      - kyb_source
                      - kyb_state
                      - kyb_state_reason
                      - kyb_state_updated_at
                      - restriction_reason
                      - restriction_kind
                      - terminated_at
                      - termination_reason
                      - created_at
                      - updated_at
                      - etag
                    type: object
                    additionalProperties: false
                    properties:
                      admission_state:
                        type: string
                        enum:
                          - admission_review
                          - admitted
                          - operational
                          - restricted
                          - offboarding
                          - terminated
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      default_master_account:
                        anyOf:
                          - type: string
                            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      etag:
                        type: string
                        minLength: 1
                      external_id:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      jurisdiction:
                        description: Country of registration, ISO 3166-1 alpha-2.
                        type: string
                        pattern: ^[A-Z]{2}$
                        minLength: 2
                        maxLength: 2
                      jurisdiction_selected:
                        type: boolean
                      kyb_source:
                        anyOf:
                          - type: string
                            enum:
                              - bootstrap
                              - sumsub
                          - type: "null"
                      kyb_stage:
                        anyOf:
                          - type: string
                            enum:
                              - form_k_ready
                              - verified
                          - type: "null"
                      kyb_state:
                        anyOf:
                          - type: string
                            enum:
                              - not_started
                              - in_progress
                              - submitted
                              - in_review
                              - resubmission_required
                              - form_k_ready
                              - verified
                              - rejected
                          - type: "null"
                      kyb_state_reason:
                        anyOf:
                          - type: string
                          - type: "null"
                      kyb_state_updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      kyc_source:
                        anyOf:
                          - type: string
                            enum:
                              - bootstrap
                              - sumsub
                          - type: "null"
                      kyc_stage:
                        anyOf:
                          - type: string
                            enum:
                              - verified
                          - type: "null"
                      legal_form:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      legal_name:
                        type: string
                        minLength: 1
                      metadata:
                        anyOf:
                          - type: object
                            additionalProperties: {}
                            propertyNames:
                              type: string
                          - type: "null"
                      resource:
                        type: string
                        const: enterprise
                      restriction_kind:
                        anyOf:
                          - type: string
                            enum:
                              - restricted
                              - suspended
                          - type: "null"
                      restriction_reason:
                        anyOf:
                          - type: string
                          - type: "null"
                      restriction_state:
                        type: string
                        enum:
                          - none
                          - restricted
                      terminated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      termination_reason:
                        anyOf:
                          - type: string
                          - type: "null"
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                  master_account:
                    required:
                      - id
                      - resource
                      - status
                      - parent
                      - tenant_type
                      - created_at
                      - updated_at
                      - etag
                    type: object
                    additionalProperties: false
                    properties:
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      display_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      etag:
                        type: string
                        minLength: 1
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      parent:
                        type: string
                        pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      resource:
                        type: string
                        const: master_account
                      status:
                        type: string
                        enum:
                          - active
                          - suspended
                          - closed
                      tenant_type:
                        type: string
                        enum:
                          - enterprise
                          - platform_operator
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                examples:
                  - enterprise:
                      admission_state: admitted
                      created_at: 2026-05-01T10:00:00Z
                      default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      etag: 2026-05-01T10:00:00.000Z
                      external_id: ent-ext-0001
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      jurisdiction: DE
                      jurisdiction_selected: false
                      kyb_source: null
                      kyb_stage: null
                      kyb_state: null
                      kyb_state_reason: null
                      kyb_state_updated_at: null
                      kyc_source: null
                      kyc_stage: null
                      legal_form: null
                      legal_name: Acme Fintech GmbH
                      metadata:
                        hq_country: DE
                        industry: fintech
                      resource: enterprise
                      restriction_kind: null
                      restriction_reason: null
                      restriction_state: none
                      terminated_at: null
                      termination_reason: null
                      updated_at: 2026-05-01T10:00:00.000Z
                    master_account:
                      created_at: 2026-05-01T10:00:00Z
                      display_name: Acme Fintech GmbH
                      etag: 2026-05-01T10:00:00.000Z
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      parent: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      resource: master_account
                      status: active
                      tenant_type: enterprise
                      updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.create
      x-required-capability:
        - enterprises.create
  /enterprises/{enterprise_id}:
    get:
      description: "Carries `first_access_method` from the onboarding record
        (`magic_link`, `passkey_enrolment` or `enterprise_idp`; `null` when the
        enterprise has none or it cannot be read), and `iam_hosting`, who hosts
        the identity stack of an `enterprise_idp` enterprise (`enterprise`: its
        own; `platform`: the shared platform login; `null` for any other method,
        for an `enterprise_idp` enterprise whose hosting is not recorded yet, or
        when there is no readable record). The list rows carry both too.
        `kyc_source`, `kyb_source` and `kyb_state_reason` (the verification
        provider and its reason) are present only for callers holding
        `enterprises.read` through an `enterprise_wildcard` grant anchored at
        `platform-operators/<id>` (platform staff); a tenant reading its own
        enterprise receives the response without them."
      summary: Get enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                admission_state: operational
                created_at: 2026-05-01T10:00:00Z
                default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 2026-05-01T10:00:00.000Z
                external_id: ent-ext-0001
                first_access_method: enterprise_idp
                iam_hosting: platform
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                jurisdiction: DE
                jurisdiction_selected: true
                kyb_stage: verified
                kyb_state: verified
                kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                kyc_stage: null
                legal_form: GmbH
                legal_name: Acme Fintech GmbH
                metadata:
                  hq_country: DE
                  industry: fintech
                resource: enterprise
                restriction_kind: null
                restriction_reason: null
                restriction_state: none
                terminated_at: null
                termination_reason: null
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - admission_state
                  - restriction_state
                  - legal_name
                  - jurisdiction
                  - jurisdiction_selected
                  - legal_form
                  - kyc_stage
                  - kyb_stage
                  - kyb_state
                  - kyb_state_updated_at
                  - restriction_reason
                  - restriction_kind
                  - terminated_at
                  - termination_reason
                  - created_at
                  - updated_at
                  - etag
                  - first_access_method
                  - iam_hosting
                type: object
                additionalProperties: false
                properties:
                  admission_state:
                    type: string
                    enum:
                      - admission_review
                      - admitted
                      - operational
                      - restricted
                      - offboarding
                      - terminated
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_master_account:
                    anyOf:
                      - type: string
                        pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  first_access_method:
                    anyOf:
                      - type: string
                        enum:
                          - magic_link
                          - passkey_enrolment
                          - enterprise_idp
                      - type: "null"
                  iam_hosting:
                    anyOf:
                      - type: string
                        enum:
                          - enterprise
                          - platform
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  jurisdiction:
                    description: Country of registration, ISO 3166-1 alpha-2.
                    type: string
                    pattern: ^[A-Z]{2}$
                    minLength: 2
                    maxLength: 2
                  jurisdiction_selected:
                    type: boolean
                  kyb_source:
                    description: Present only for callers with platform-wide `enterprises.read`
                      authority; omitted for tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    description: Present only for callers with platform-wide `enterprises.read`
                      authority; omitted for tenant callers.
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    description: Present only for callers with platform-wide `enterprises.read`
                      authority; omitted for tenant callers.
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  legal_form:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  legal_name:
                    type: string
                    minLength: 1
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: enterprise
                  restriction_kind:
                    anyOf:
                      - type: string
                        enum:
                          - restricted
                          - suspended
                      - type: "null"
                  restriction_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  restriction_state:
                    type: string
                    enum:
                      - none
                      - restricted
                  terminated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  termination_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - admission_state: operational
                    created_at: 2026-05-01T10:00:00Z
                    default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 2026-05-01T10:00:00.000Z
                    external_id: ent-ext-0001
                    first_access_method: enterprise_idp
                    iam_hosting: platform
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    jurisdiction: DE
                    jurisdiction_selected: true
                    kyb_stage: verified
                    kyb_state: verified
                    kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                    kyc_stage: null
                    legal_form: GmbH
                    legal_name: Acme Fintech GmbH
                    metadata:
                      hq_country: DE
                      industry: fintech
                    resource: enterprise
                    restriction_kind: null
                    restriction_reason: null
                    restriction_state: none
                    terminated_at: null
                    termination_reason: null
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.get
      x-required-capability:
        - enterprises.read
  /enterprises/{enterprise_id}/close:
    post:
      description: "Platform-actor-only; enterprise-scoped actors cannot perform this
        action. Permanently terminates the enterprise perimeter. A reason is
        required and audited. Returns the updated enterprise resource. A `503`
        with reason `termination_outcome_unknown` means the enterprise’s access
        is already closed but its termination is unconfirmed: repeat the
        request. A `409` with reason `enterprise_already_terminated` on the
        repeat confirms the close."
      summary: Close enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              reason: Sanctions screening hit under review (case CMP-1042)
            schema:
              required:
                - reason
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 3
                  maxLength: 2000
              examples:
                - reason: Sanctions screening hit under review (case CMP-1042)
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                admission_state: terminated
                created_at: 2026-05-01T10:00:00Z
                default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 2026-05-01T10:00:00.000Z
                external_id: ent-ext-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                jurisdiction: DE
                jurisdiction_selected: true
                kyb_source: sumsub
                kyb_stage: verified
                kyb_state: verified
                kyb_state_reason: null
                kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                kyc_source: null
                kyc_stage: null
                legal_form: GmbH
                legal_name: Acme Fintech GmbH
                metadata:
                  hq_country: DE
                  industry: fintech
                resource: enterprise
                restriction_kind: null
                restriction_reason: null
                restriction_state: none
                terminated_at: 2026-05-01T10:00:00Z
                termination_reason: Sanctions screening hit under review (case CMP-1042)
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - admission_state
                  - restriction_state
                  - legal_name
                  - jurisdiction
                  - jurisdiction_selected
                  - legal_form
                  - kyc_stage
                  - kyc_source
                  - kyb_stage
                  - kyb_source
                  - kyb_state
                  - kyb_state_reason
                  - kyb_state_updated_at
                  - restriction_reason
                  - restriction_kind
                  - terminated_at
                  - termination_reason
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  admission_state:
                    type: string
                    enum:
                      - admission_review
                      - admitted
                      - operational
                      - restricted
                      - offboarding
                      - terminated
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_master_account:
                    anyOf:
                      - type: string
                        pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  jurisdiction:
                    type: string
                    pattern: ^[A-Z]{2}$
                    minLength: 2
                    maxLength: 2
                  jurisdiction_selected:
                    type: boolean
                  kyb_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  legal_form:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  legal_name:
                    type: string
                    minLength: 1
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: enterprise
                  restriction_kind:
                    anyOf:
                      - type: string
                        enum:
                          - restricted
                          - suspended
                      - type: "null"
                  restriction_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  restriction_state:
                    type: string
                    enum:
                      - none
                      - restricted
                  terminated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  termination_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - admission_state: terminated
                    created_at: 2026-05-01T10:00:00Z
                    default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 2026-05-01T10:00:00.000Z
                    external_id: ent-ext-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    jurisdiction: DE
                    jurisdiction_selected: true
                    kyb_source: sumsub
                    kyb_stage: verified
                    kyb_state: verified
                    kyb_state_reason: null
                    kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                    kyc_source: null
                    kyc_stage: null
                    legal_form: GmbH
                    legal_name: Acme Fintech GmbH
                    metadata:
                      hq_country: DE
                      industry: fintech
                    resource: enterprise
                    restriction_kind: null
                    restriction_reason: null
                    restriction_state: none
                    terminated_at: 2026-05-01T10:00:00Z
                    termination_reason: Sanctions screening hit under review (case CMP-1042)
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.close
      x-required-capability:
        - enterprises.terminate
  /enterprises/{enterprise_id}/first-access:
    get:
      description: Returns registration readiness for an enterprise using
        `enterprise_idp` first access, whether its provisioning administrator
        has bound an identity, and the latest first-access command delivery.
        This applies to both enterprise-hosted and platform-hosted identity
        stacks. Delivery is null if no delivery exists or that lookup is
        unavailable. Returns `404` for another first-access method. Requires a
        platform-operator binding and `enterprises.provision` on an
        `enterprise_wildcard` grant anchored at `platform-operators/<id>`.
      summary: Read enterprise first-access status
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              schema:
                required:
                  - state
                  - failing_step
                  - last_event_id
                  - last_delivery
                  - conflict_reason
                type: object
                additionalProperties: false
                properties:
                  conflict_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  failing_step:
                    anyOf:
                      - type: string
                        enum:
                          - identity_provider
                          - probe
                          - service_account
                          - identity_subscription
                          - command_subscription
                      - type: "null"
                  last_delivery:
                    anyOf:
                      - required:
                          - status
                          - attempted_at
                          - subscription_id
                          - delivery_id
                        type: object
                        additionalProperties: false
                        properties:
                          attempted_at:
                            anyOf:
                              - anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              - type: "null"
                          delivery_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          status:
                            type: string
                            enum:
                              - pending
                              - delivered
                              - failed
                              - retrying
                              - dlq
                          subscription_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                      - type: "null"
                  last_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  state:
                    type: string
                    enum:
                      - waiting_for_stack
                      - ready
                      - bound
                      - conflict
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.first_access
      x-required-capability:
        - enterprises.provision
  /enterprises/{enterprise_id}/first-access/resend:
    post:
      description: Resends access to the provisioned administrator. Requires a
        platform-operator binding and an `enterprise_wildcard` grant anchored at
        `platform-operators/<id>` for `enterprises.provision`. Send no request
        body. For `enterprise_idp`, the identity stack must be ready and
        provisioning must have created the administrator; the response contains
        the emitted `event_id`. That path is limited to one resend per user per
        five minutes. For a hosted first-access method, returns the enterprise,
        administrator and first-access delivery result. Hosted resend is
        unavailable in production (`409 state_conflict`, `data.reason =
        not_supported`).
      summary: Resend enterprise first access
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                examples:
                  - event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                anyOf:
                  - required:
                      - enterprise_ref
                      - human_actor_id
                      - first_access
                    type: object
                    additionalProperties: false
                    properties:
                      enterprise_ref:
                        type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      first_access:
                        required:
                          - method
                          - sent
                        type: object
                        additionalProperties: false
                        properties:
                          method:
                            type: string
                            enum:
                              - magic_link
                              - passkey_enrolment
                              - enterprise_idp
                          sent:
                            type: boolean
                      human_actor_id:
                        type: string
                  - required:
                      - event_id
                    type: object
                    additionalProperties: false
                    properties:
                      event_id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.resend.create
      x-required-capability:
        - enterprises.provision
  /enterprises/{enterprise_id}/mfa-assurance:
    parameters:
      - name: enterprise_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: Read the MFA assurance setting for this scope. Requires
        policies.read covering the target scope. own_mode is null when this
        scope inherits its policy; effective_mode and source_scope_ref describe
        the resolved policy. owner identifies a scope-owned or platform-owned
        local row and is null when no local row exists. With no setting in the
        lineage, effective_mode is optional and source_scope_ref is null.
        Platform human sessions always have a mandatory MFA floor independent of
        these enterprise/client settings.
      summary: Read enterprise MFA policy
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                effective_mode: mandatory
                own_mode: mandatory
                owner: scope
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                source_scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - scope_ref
                  - own_mode
                  - effective_mode
                  - source_scope_ref
                type: object
                additionalProperties: false
                properties:
                  effective_mode:
                    type: string
                    enum:
                      - optional
                      - mandatory
                  own_mode:
                    anyOf:
                      - type: string
                        enum:
                          - optional
                          - mandatory
                      - type: "null"
                  owner:
                    anyOf:
                      - type: string
                        enum:
                          - scope
                          - platform
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  source_scope_ref:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                examples:
                  - effective_mode: mandatory
                    own_mode: mandatory
                    owner: scope
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    source_scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.mfa_assurance.get
      x-required-capability:
        - policies.read
    put:
      description: Requires both policies.manage and policies.read covering the target
        scope; the current setting is read for the audit diff before writing.
        Set mode to inherited to remove the scope setting. Setting optional
        beneath a mandatory ancestor returns HTTP 409 with
        data.reason=mfa_cannot_relax and data.resource naming that ancestor. A
        platform-owned setting may only be changed by platform staff with
        platform-wide policies.manage authority; other callers receive HTTP 403
        with data.reason=mfa_setting_platform_owned. The required reason is
        trimmed and must contain 3 to 500 characters for the audit record. This
        changes the assurance policy; it does not enroll or remove an
        authentication factor.
      summary: Set enterprise MFA policy
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            example:
              mode: mandatory
              reason: Require fresh authentication for protected actions
            schema:
              required:
                - mode
                - reason
              type: object
              additionalProperties: false
              properties:
                mode:
                  anyOf:
                    - type: string
                      const: inherited
                    - type: string
                      enum:
                        - optional
                        - mandatory
                reason:
                  type: string
                  minLength: 3
                  maxLength: 500
              examples:
                - mode: mandatory
                  reason: Require fresh authentication for protected actions
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                effective_mode: mandatory
                own_mode: mandatory
                owner: scope
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                source_scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - scope_ref
                  - own_mode
                  - effective_mode
                  - source_scope_ref
                type: object
                additionalProperties: false
                properties:
                  effective_mode:
                    type: string
                    enum:
                      - optional
                      - mandatory
                  own_mode:
                    anyOf:
                      - type: string
                        enum:
                          - optional
                          - mandatory
                      - type: "null"
                  owner:
                    anyOf:
                      - type: string
                        enum:
                          - scope
                          - platform
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  source_scope_ref:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                examples:
                  - effective_mode: mandatory
                    own_mode: mandatory
                    owner: scope
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    source_scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.mfa_assurance.set
      x-required-capability:
        - policies.manage
        - policies.read
  /enterprises/{enterprise_id}/provision:
    post:
      description: "Configures the designated administrator, roles and commercial
        agreements for an enterprise already created with `POST /enterprises`.
        Requires a platform-operator binding and an `enterprise_wildcard` grant
        anchored at `platform-operators/<id>` for `enterprises.provision`.
        Supply the contracted `service_types` and `platform_fee_bps`;
        `enterprise_fee_bps` defaults to 0. Provisioning is resumable: completed
        work is reported as `reused` on later runs. Production supports
        `first_access_method=enterprise_idp`; hosted magic-link and passkey
        first access are deployment-dependent. An `enterprise_idp` response
        reports `first_access.sent=false`; once its identity stack is ready, use
        the first-access resend endpoint to issue the command."
      summary: Provision an admitted enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              designated_admin:
                display_name: Acme Admin
                email: admin@acme.example
              enterprise_fee_bps: 0
              first_access_method: enterprise_idp
              iam_hosting: enterprise
              platform_fee_bps: 10
              service_types:
                - custody
                - deposit_fiat
                - withdrawal_fiat
            schema:
              required:
                - designated_admin
                - service_types
                - platform_fee_bps
              type: object
              additionalProperties: false
              properties:
                designated_admin:
                  required:
                    - email
                  type: object
                  additionalProperties: false
                  properties:
                    display_name:
                      anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 200
                        - type: "null"
                    email:
                      type: string
                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                      maxLength: 254
                      format: email
                effective_from:
                  type: string
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                  format: date-time
                enterprise_fee_bps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                  default: 0
                first_access_method:
                  type: string
                  enum:
                    - magic_link
                    - passkey_enrolment
                    - enterprise_idp
                iam_hosting:
                  type: string
                  enum:
                    - enterprise
                    - platform
                platform_fee_bps:
                  type: integer
                  minimum: 0
                  maximum: 10000
                service_types:
                  type: array
                  items:
                    type: string
                    enum:
                      - custody
                      - conversion
                      - withdrawal_crypto
                      - withdrawal_fiat
                      - deposit_crypto
                      - deposit_fiat
                      - internal_transfer
                      - staking
                  minItems: 1
              examples:
                - designated_admin:
                    display_name: Acme Admin
                    email: admin@acme.example
                  enterprise_fee_bps: 0
                  first_access_method: enterprise_idp
                  iam_hosting: enterprise
                  platform_fee_bps: 10
                  service_types:
                    - custody
                    - deposit_fiat
                    - withdrawal_fiat
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                admin_role_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                first_access:
                  method: enterprise_idp
                  sent: false
                human_actor_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_provider_id: null
                integration_role_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operator_role_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                steps:
                  - status: completed
                    step: human_actor
              schema:
                required:
                  - enterprise_ref
                  - identity_provider_id
                  - human_actor_id
                  - admin_role_id
                  - operator_role_id
                  - integration_role_id
                  - first_access
                  - steps
                type: object
                additionalProperties: false
                properties:
                  admin_role_id:
                    type: string
                  enterprise_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  first_access:
                    required:
                      - method
                      - sent
                    type: object
                    additionalProperties: false
                    properties:
                      method:
                        type: string
                        enum:
                          - magic_link
                          - passkey_enrolment
                          - enterprise_idp
                      sent:
                        type: boolean
                  human_actor_id:
                    type: string
                  identity_provider_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  integration_role_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  operator_role_id:
                    type: string
                  steps:
                    type: array
                    items:
                      required:
                        - step
                        - status
                      type: object
                      additionalProperties: false
                      properties:
                        status:
                          type: string
                          enum:
                            - completed
                            - reused
                        step:
                          type: string
                examples:
                  - admin_role_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    first_access:
                      method: enterprise_idp
                      sent: false
                    human_actor_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_provider_id: null
                    integration_role_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operator_role_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    steps:
                      - status: completed
                        step: human_actor
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.provision
      x-required-capability:
        - enterprises.provision
  /enterprises/{enterprise_id}/reactivate:
    post:
      description: Platform-actor-only; enterprise-scoped actors cannot perform this
        action. Lifts a restriction or suspension and re-enables hosted logins.
        A reason is required and audited. A `503` with reason
        `reactivation_outcome_unknown` means the reactivation is unconfirmed and
        nothing was handed back; edge tried to put the restriction back. Repeat
        the request; if the repeat is refused as not restricted, suspend the
        enterprise and reactivate it again.
      summary: Reactivate enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              reason: Sanctions screening hit under review (case CMP-1042)
            schema:
              required:
                - reason
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 3
                  maxLength: 2000
              examples:
                - reason: Sanctions screening hit under review (case CMP-1042)
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                admission_state: operational
                created_at: 2026-05-01T10:00:00Z
                default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 2026-05-01T10:00:00.000Z
                external_id: ent-ext-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                jurisdiction: DE
                jurisdiction_selected: true
                kyb_source: sumsub
                kyb_stage: verified
                kyb_state: verified
                kyb_state_reason: null
                kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                kyc_source: null
                kyc_stage: null
                legal_form: GmbH
                legal_name: Acme Fintech GmbH
                metadata:
                  hq_country: DE
                  industry: fintech
                resource: enterprise
                restriction_kind: null
                restriction_reason: null
                restriction_state: none
                terminated_at: null
                termination_reason: null
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - admission_state
                  - restriction_state
                  - legal_name
                  - jurisdiction
                  - jurisdiction_selected
                  - legal_form
                  - kyc_stage
                  - kyc_source
                  - kyb_stage
                  - kyb_source
                  - kyb_state
                  - kyb_state_reason
                  - kyb_state_updated_at
                  - restriction_reason
                  - restriction_kind
                  - terminated_at
                  - termination_reason
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  admission_state:
                    type: string
                    enum:
                      - admission_review
                      - admitted
                      - operational
                      - restricted
                      - offboarding
                      - terminated
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_master_account:
                    anyOf:
                      - type: string
                        pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  jurisdiction:
                    type: string
                    pattern: ^[A-Z]{2}$
                    minLength: 2
                    maxLength: 2
                  jurisdiction_selected:
                    type: boolean
                  kyb_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  legal_form:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  legal_name:
                    type: string
                    minLength: 1
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: enterprise
                  restriction_kind:
                    anyOf:
                      - type: string
                        enum:
                          - restricted
                          - suspended
                      - type: "null"
                  restriction_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  restriction_state:
                    type: string
                    enum:
                      - none
                      - restricted
                  terminated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  termination_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - admission_state: operational
                    created_at: 2026-05-01T10:00:00Z
                    default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 2026-05-01T10:00:00.000Z
                    external_id: ent-ext-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    jurisdiction: DE
                    jurisdiction_selected: true
                    kyb_source: sumsub
                    kyb_stage: verified
                    kyb_state: verified
                    kyb_state_reason: null
                    kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                    kyc_source: null
                    kyc_stage: null
                    legal_form: GmbH
                    legal_name: Acme Fintech GmbH
                    metadata:
                      hq_country: DE
                      industry: fintech
                    resource: enterprise
                    restriction_kind: null
                    restriction_reason: null
                    restriction_state: none
                    terminated_at: null
                    termination_reason: null
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.reactivate
      x-required-capability:
        - enterprises.reactivate
  /enterprises/{enterprise_id}/restrict:
    post:
      description: Platform-actor-only; enterprise-scoped actors cannot perform this
        action. Pauses the enterprise’s operations while its people keep signing
        in and reading. A reason is required and audited. Returns the updated
        enterprise resource.
      summary: Restrict enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              reason: Sanctions screening hit under review (case CMP-1042)
            schema:
              required:
                - reason
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 3
                  maxLength: 2000
              examples:
                - reason: Sanctions screening hit under review (case CMP-1042)
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                admission_state: operational
                created_at: 2026-05-01T10:00:00Z
                default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 2026-05-01T10:00:00.000Z
                external_id: ent-ext-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                jurisdiction: DE
                jurisdiction_selected: true
                kyb_source: sumsub
                kyb_stage: verified
                kyb_state: verified
                kyb_state_reason: null
                kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                kyc_source: null
                kyc_stage: null
                legal_form: GmbH
                legal_name: Acme Fintech GmbH
                metadata:
                  hq_country: DE
                  industry: fintech
                resource: enterprise
                restriction_kind: restricted
                restriction_reason: Sanctions screening hit under review (case CMP-1042)
                restriction_state: restricted
                terminated_at: null
                termination_reason: null
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - admission_state
                  - restriction_state
                  - legal_name
                  - jurisdiction
                  - jurisdiction_selected
                  - legal_form
                  - kyc_stage
                  - kyc_source
                  - kyb_stage
                  - kyb_source
                  - kyb_state
                  - kyb_state_reason
                  - kyb_state_updated_at
                  - restriction_reason
                  - restriction_kind
                  - terminated_at
                  - termination_reason
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  admission_state:
                    type: string
                    enum:
                      - admission_review
                      - admitted
                      - operational
                      - restricted
                      - offboarding
                      - terminated
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_master_account:
                    anyOf:
                      - type: string
                        pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  jurisdiction:
                    type: string
                    pattern: ^[A-Z]{2}$
                    minLength: 2
                    maxLength: 2
                  jurisdiction_selected:
                    type: boolean
                  kyb_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  legal_form:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  legal_name:
                    type: string
                    minLength: 1
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: enterprise
                  restriction_kind:
                    anyOf:
                      - type: string
                        enum:
                          - restricted
                          - suspended
                      - type: "null"
                  restriction_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  restriction_state:
                    type: string
                    enum:
                      - none
                      - restricted
                  terminated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  termination_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - admission_state: operational
                    created_at: 2026-05-01T10:00:00Z
                    default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 2026-05-01T10:00:00.000Z
                    external_id: ent-ext-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    jurisdiction: DE
                    jurisdiction_selected: true
                    kyb_source: sumsub
                    kyb_stage: verified
                    kyb_state: verified
                    kyb_state_reason: null
                    kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                    kyc_source: null
                    kyc_stage: null
                    legal_form: GmbH
                    legal_name: Acme Fintech GmbH
                    metadata:
                      hq_country: DE
                      industry: fintech
                    resource: enterprise
                    restriction_kind: restricted
                    restriction_reason: Sanctions screening hit under review (case CMP-1042)
                    restriction_state: restricted
                    terminated_at: null
                    termination_reason: null
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.restrict
      x-required-capability:
        - enterprises.restrict
  /enterprises/{enterprise_id}/suspend:
    post:
      description: "Platform-actor-only; enterprise-scoped actors cannot perform this
        action. Requires `enterprises.restrict`. Restricts the enterprise and
        ends its hosted logins until it is reactivated. A reason is required and
        audited. Returns the updated enterprise resource. Suspending an
        enterprise that is already suspended ends its access again and succeeds;
        the standing suspension and its reason are kept, and the new reason is
        not recorded on the enterprise. A `503` with reason
        `suspension_outcome_unknown` means the suspension may or may not have
        landed and its logins and sessions were not ended: repeat the request."
      summary: Suspend enterprise
      tags:
        - Activation
        - Enterprises
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              reason: Sanctions screening hit under review (case CMP-1042)
            schema:
              required:
                - reason
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  minLength: 3
                  maxLength: 2000
              examples:
                - reason: Sanctions screening hit under review (case CMP-1042)
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                admission_state: operational
                created_at: 2026-05-01T10:00:00Z
                default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 2026-05-01T10:00:00.000Z
                external_id: ent-ext-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                jurisdiction: DE
                jurisdiction_selected: true
                kyb_source: sumsub
                kyb_stage: verified
                kyb_state: verified
                kyb_state_reason: null
                kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                kyc_source: null
                kyc_stage: null
                legal_form: GmbH
                legal_name: Acme Fintech GmbH
                metadata:
                  hq_country: DE
                  industry: fintech
                resource: enterprise
                restriction_kind: suspended
                restriction_reason: Sanctions screening hit under review (case CMP-1042)
                restriction_state: restricted
                terminated_at: null
                termination_reason: null
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - admission_state
                  - restriction_state
                  - legal_name
                  - jurisdiction
                  - jurisdiction_selected
                  - legal_form
                  - kyc_stage
                  - kyc_source
                  - kyb_stage
                  - kyb_source
                  - kyb_state
                  - kyb_state_reason
                  - kyb_state_updated_at
                  - restriction_reason
                  - restriction_kind
                  - terminated_at
                  - termination_reason
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  admission_state:
                    type: string
                    enum:
                      - admission_review
                      - admitted
                      - operational
                      - restricted
                      - offboarding
                      - terminated
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  default_master_account:
                    anyOf:
                      - type: string
                        pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  jurisdiction:
                    type: string
                    pattern: ^[A-Z]{2}$
                    minLength: 2
                    maxLength: 2
                  jurisdiction_selected:
                    type: boolean
                  kyb_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyb_stage:
                    anyOf:
                      - type: string
                        enum:
                          - form_k_ready
                          - verified
                      - type: "null"
                  kyb_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_started
                          - in_progress
                          - submitted
                          - in_review
                          - resubmission_required
                          - form_k_ready
                          - verified
                          - rejected
                      - type: "null"
                  kyb_state_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  kyb_state_updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  kyc_source:
                    anyOf:
                      - type: string
                        enum:
                          - bootstrap
                          - sumsub
                      - type: "null"
                  kyc_stage:
                    anyOf:
                      - type: string
                        enum:
                          - verified
                      - type: "null"
                  legal_form:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  legal_name:
                    type: string
                    minLength: 1
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  resource:
                    type: string
                    const: enterprise
                  restriction_kind:
                    anyOf:
                      - type: string
                        enum:
                          - restricted
                          - suspended
                      - type: "null"
                  restriction_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  restriction_state:
                    type: string
                    enum:
                      - none
                      - restricted
                  terminated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  termination_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - admission_state: operational
                    created_at: 2026-05-01T10:00:00Z
                    default_master_account: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 2026-05-01T10:00:00.000Z
                    external_id: ent-ext-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    jurisdiction: DE
                    jurisdiction_selected: true
                    kyb_source: sumsub
                    kyb_stage: verified
                    kyb_state: verified
                    kyb_state_reason: null
                    kyb_state_updated_at: 2026-05-01T10:00:00.000Z
                    kyc_source: null
                    kyc_stage: null
                    legal_form: GmbH
                    legal_name: Acme Fintech GmbH
                    metadata:
                      hq_country: DE
                      industry: fintech
                    resource: enterprise
                    restriction_kind: suspended
                    restriction_reason: Sanctions screening hit under review (case CMP-1042)
                    restriction_state: restricted
                    terminated_at: null
                    termination_reason: null
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: enterprises.suspend
      x-required-capability:
        - enterprises.restrict
  /events:
    get:
      description: Lists tenant-visible platform events. If omitted, `scope_ref` is
        derived from the authenticated enterprise or client context.
      summary: List events
      tags:
        - Distribution
        - Events
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(enterprises|clients|master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - name: from_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                format: date-time
              - type: string
                format: date-time
        - name: to_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                format: date-time
              - type: string
                format: date-time
        - name: actor_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: aggregate_type
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: aggregate_id
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: event_type
          in: query
          required: false
          schema:
            anyOf:
              - description: Canonical public webhook event type.
                type: string
                enum:
                  - tenant.enterprise.admission_reviewed.v1
                  - tenant.enterprise.admitted.v1
                  - tenant.enterprise.activated.v1
                  - tenant.enterprise.updated.v1
                  - tenant.enterprise.suspended.v1
                  - tenant.enterprise.reactivated.v1
                  - tenant.enterprise.closed.v1
                  - tenant.enterprise.terminated.v1
                  - tenant.platform_operator.admitted.v1
                  - tenant.platform_operator.restricted.v1
                  - tenant.platform_operator.reactivated.v1
                  - tenant.platform_operator.offboarded.v1
                  - tenant.platform_operator.catalog_updated.v1
                  - tenant.master_account.created.v1
                  - tenant.master_account.suspended.v1
                  - tenant.master_account.closed.v1
                  - tenant.client.created.v1
                  - tenant.client.updated.v1
                  - tenant.client.suspended.v1
                  - tenant.client.reactivated.v1
                  - tenant.client.closed.v1
                  - tenant.client_account.created.v1
                  - tenant.client_account.suspended.v1
                  - tenant.client_account.reactivated.v1
                  - tenant.client_account.closed.v1
                  - ledger.transaction.posted.v1
                  - operations.withdrawal.requested.v1
                  - operations.withdrawal.admissible.v1
                  - operations.withdrawal.executing.v1
                  - operations.withdrawal.pending_approval.v1
                  - operations.withdrawal.pending_compliance.v1
                  - operations.withdrawal.approved.v1
                  - operations.withdrawal.settled.v1
                  - operations.withdrawal.failed.v1
                  - operations.withdrawal.cancelled.v1
                  - operations.conversion.requested.v1
                  - operations.conversion.admissible.v1
                  - operations.conversion.pending_approval.v1
                  - operations.conversion.pending_compliance.v1
                  - operations.conversion.approved.v1
                  - operations.conversion.settled.v1
                  - operations.conversion.failed.v1
                  - operations.conversion.cancelled.v1
                  - operations.external_settlement_conversion.pending_compliance.v1
                  - operations.internal_transfer.requested.v1
                  - operations.internal_transfer.admissible.v1
                  - operations.internal_transfer.pending_approval.v1
                  - operations.internal_transfer.pending_compliance.v1
                  - operations.internal_transfer.approved.v1
                  - operations.internal_transfer.settled.v1
                  - operations.internal_transfer.failed.v1
                  - operations.internal_transfer.cancelled.v1
                  - operations.on_ramp.requested.v1
                  - operations.on_ramp.admissible.v1
                  - operations.on_ramp.pending_approval.v1
                  - operations.on_ramp.pending_compliance.v1
                  - operations.on_ramp.approved.v1
                  - operations.on_ramp.settled.v1
                  - operations.on_ramp.failed.v1
                  - operations.on_ramp.cancelled.v1
                  - operations.off_ramp.requested.v1
                  - operations.off_ramp.admissible.v1
                  - operations.off_ramp.pending_approval.v1
                  - operations.off_ramp.pending_compliance.v1
                  - operations.off_ramp.approved.v1
                  - operations.off_ramp.settled.v1
                  - operations.off_ramp.failed.v1
                  - operations.off_ramp.cancelled.v1
                  - operations.deposit.requested.v1
                  - operations.deposit.admissible.v1
                  - operations.deposit.pending_approval.v1
                  - operations.deposit.pending_admission.v1
                  - operations.deposit.pending_compliance.v1
                  - operations.deposit.approved.v1
                  - operations.deposit.settled.v1
                  - operations.deposit.failed.v1
                  - operations.deposit.cancelled.v1
                  - rails.deposit.detected.v1
                  - rails.dispatch.acknowledged.v1
                  - rails.dispatch.rejected.v1
                  - rails.settlement.confirmed.v1
                  - kyc.verification.reviewed.v1
                  - loan.originated.v1
                  - loan.origination_failed.v1
                  - loan.margin_called.v1
                  - loan.margin_call_cleared.v1
                  - loan.liquidation_halted.v1
                  - loan.liquidated.v1
                  - loan.repaid.v1
                  - loan.extended.v1
                  - loan.closed.v1
                  - loan.force_closed.v1
                  - loan.reconciliation_discrepancy.v1
              - type: array
                items:
                  description: Canonical public webhook event type.
                  type: string
                  enum:
                    - tenant.enterprise.admission_reviewed.v1
                    - tenant.enterprise.admitted.v1
                    - tenant.enterprise.activated.v1
                    - tenant.enterprise.updated.v1
                    - tenant.enterprise.suspended.v1
                    - tenant.enterprise.reactivated.v1
                    - tenant.enterprise.closed.v1
                    - tenant.enterprise.terminated.v1
                    - tenant.platform_operator.admitted.v1
                    - tenant.platform_operator.restricted.v1
                    - tenant.platform_operator.reactivated.v1
                    - tenant.platform_operator.offboarded.v1
                    - tenant.platform_operator.catalog_updated.v1
                    - tenant.master_account.created.v1
                    - tenant.master_account.suspended.v1
                    - tenant.master_account.closed.v1
                    - tenant.client.created.v1
                    - tenant.client.updated.v1
                    - tenant.client.suspended.v1
                    - tenant.client.reactivated.v1
                    - tenant.client.closed.v1
                    - tenant.client_account.created.v1
                    - tenant.client_account.suspended.v1
                    - tenant.client_account.reactivated.v1
                    - tenant.client_account.closed.v1
                    - ledger.transaction.posted.v1
                    - operations.withdrawal.requested.v1
                    - operations.withdrawal.admissible.v1
                    - operations.withdrawal.executing.v1
                    - operations.withdrawal.pending_approval.v1
                    - operations.withdrawal.pending_compliance.v1
                    - operations.withdrawal.approved.v1
                    - operations.withdrawal.settled.v1
                    - operations.withdrawal.failed.v1
                    - operations.withdrawal.cancelled.v1
                    - operations.conversion.requested.v1
                    - operations.conversion.admissible.v1
                    - operations.conversion.pending_approval.v1
                    - operations.conversion.pending_compliance.v1
                    - operations.conversion.approved.v1
                    - operations.conversion.settled.v1
                    - operations.conversion.failed.v1
                    - operations.conversion.cancelled.v1
                    - operations.external_settlement_conversion.pending_compliance.v1
                    - operations.internal_transfer.requested.v1
                    - operations.internal_transfer.admissible.v1
                    - operations.internal_transfer.pending_approval.v1
                    - operations.internal_transfer.pending_compliance.v1
                    - operations.internal_transfer.approved.v1
                    - operations.internal_transfer.settled.v1
                    - operations.internal_transfer.failed.v1
                    - operations.internal_transfer.cancelled.v1
                    - operations.on_ramp.requested.v1
                    - operations.on_ramp.admissible.v1
                    - operations.on_ramp.pending_approval.v1
                    - operations.on_ramp.pending_compliance.v1
                    - operations.on_ramp.approved.v1
                    - operations.on_ramp.settled.v1
                    - operations.on_ramp.failed.v1
                    - operations.on_ramp.cancelled.v1
                    - operations.off_ramp.requested.v1
                    - operations.off_ramp.admissible.v1
                    - operations.off_ramp.pending_approval.v1
                    - operations.off_ramp.pending_compliance.v1
                    - operations.off_ramp.approved.v1
                    - operations.off_ramp.settled.v1
                    - operations.off_ramp.failed.v1
                    - operations.off_ramp.cancelled.v1
                    - operations.deposit.requested.v1
                    - operations.deposit.admissible.v1
                    - operations.deposit.pending_approval.v1
                    - operations.deposit.pending_admission.v1
                    - operations.deposit.pending_compliance.v1
                    - operations.deposit.approved.v1
                    - operations.deposit.settled.v1
                    - operations.deposit.failed.v1
                    - operations.deposit.cancelled.v1
                    - rails.deposit.detected.v1
                    - rails.dispatch.acknowledged.v1
                    - rails.dispatch.rejected.v1
                    - rails.settlement.confirmed.v1
                    - kyc.verification.reviewed.v1
                    - loan.originated.v1
                    - loan.origination_failed.v1
                    - loan.margin_called.v1
                    - loan.margin_call_cleared.v1
                    - loan.liquidation_halted.v1
                    - loan.liquidated.v1
                    - loan.repaid.v1
                    - loan.extended.v1
                    - loan.closed.v1
                    - loan.force_closed.v1
                    - loan.reconciliation_discrepancy.v1
                minItems: 1
        - name: event_type_pattern
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: trace_id
          in: query
          required: false
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - aggregate:
                      type: withdrawal
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    data:
                      account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      failure_reason: null
                      family: withdrawal
                      fee_summary:
                        components:
                          - amount:
                              currency: USDC
                              value: "1.00"
                            kind: network_fee
                        total:
                          currency: USDC
                          value: "1.00"
                      fill_rate: null
                      occurred_at: 2026-05-01T10:00:00Z
                      operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      principal_amount:
                        currency: USDC
                        value: "250.00"
                      scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      status: settled
                    event_type: operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    metadata: null
                    occurred_at: 2026-05-01T10:00:00Z
                    partition_key: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    published_at: 2026-05-01T10:00:00Z
                    resource: event
                    schema_version: 1
                    scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    trace_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - event_type
                        - schema_version
                        - occurred_at
                        - published_at
                        - aggregate
                        - partition_key
                        - trace_id
                        - subject_attribution
                        - scope_ref
                        - data
                        - metadata
                      type: object
                      additionalProperties: false
                      properties:
                        aggregate:
                          required:
                            - type
                            - id
                          type: object
                          additionalProperties: false
                          properties:
                            type:
                              type: string
                              minLength: 1
                            id:
                              type: string
                              minLength: 1
                        data:
                          type: object
                          additionalProperties: {}
                          propertyNames:
                            type: string
                        event_type:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        metadata:
                          anyOf:
                            - type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            - type: "null"
                        occurred_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        partition_key:
                          type: string
                          minLength: 1
                        published_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        resource:
                          type: string
                          const: event
                        schema_version:
                          type: integer
                          maximum: 9007199254740991
                          exclusiveMinimum: 0
                        scope_ref:
                          anyOf:
                            - type: string
                              pattern: ^(enterprises|clients|master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        subject_attribution:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                            - federation
                            - enterprise_binding
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            authenticated_principal:
                              required:
                                - id
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                tenant_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            enterprise_binding:
                              required:
                                - topology_ref
                                - tenant_type
                              type: object
                              additionalProperties: false
                              properties:
                                tenant_type:
                                  type: string
                                  enum:
                                    - enterprise
                                    - platform_operator
                                topology_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            federation:
                              anyOf:
                                - required:
                                    - issuer
                                    - external_subject
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    external_subject:
                                      type: string
                                      minLength: 1
                                    issuer:
                                      type: string
                                      minLength: 1
                                - type: "null"
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                        trace_id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - aggregate:
                          type: withdrawal
                          id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        data:
                          account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          failure_reason: null
                          family: withdrawal
                          fee_summary:
                            components:
                              - amount:
                                  currency: USDC
                                  value: "1.00"
                                kind: network_fee
                            total:
                              currency: USDC
                              value: "1.00"
                          fill_rate: null
                          occurred_at: 2026-05-01T10:00:00Z
                          operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          principal_amount:
                            currency: USDC
                            value: "250.00"
                          scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          status: settled
                        event_type: operations.withdrawal.settled.v1
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        metadata: null
                        occurred_at: 2026-05-01T10:00:00Z
                        partition_key: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        published_at: 2026-05-01T10:00:00Z
                        resource: event
                        schema_version: 1
                        scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        trace_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: events.list
      x-required-capability:
        - events.read
  /events/{event_id}:
    get:
      summary: Get event
      tags:
        - Distribution
        - Events
      security:
        - BearerAuth: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                aggregate:
                  type: withdrawal
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                data:
                  account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  failure_reason: null
                  family: withdrawal
                  fee_summary:
                    components:
                      - amount:
                          currency: USDC
                          value: "1.00"
                        kind: network_fee
                    total:
                      currency: USDC
                      value: "1.00"
                  fill_rate: null
                  occurred_at: 2026-05-01T10:00:00Z
                  operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  principal_amount:
                    currency: USDC
                    value: "250.00"
                  scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  status: settled
                event_type: operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                metadata: null
                occurred_at: 2026-05-01T10:00:00Z
                partition_key: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                published_at: 2026-05-01T10:00:00Z
                resource: event
                schema_version: 1
                scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                trace_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - id
                  - resource
                  - event_type
                  - schema_version
                  - occurred_at
                  - published_at
                  - aggregate
                  - partition_key
                  - trace_id
                  - subject_attribution
                  - scope_ref
                  - data
                  - metadata
                type: object
                additionalProperties: false
                properties:
                  aggregate:
                    required:
                      - type
                      - id
                    type: object
                    additionalProperties: false
                    properties:
                      type:
                        type: string
                        minLength: 1
                      id:
                        type: string
                        minLength: 1
                  data:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  event_type:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  metadata:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  occurred_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  partition_key:
                    type: string
                    minLength: 1
                  published_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  resource:
                    type: string
                    const: event
                  schema_version:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|clients|master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  trace_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - aggregate:
                      type: withdrawal
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    data:
                      account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      failure_reason: null
                      family: withdrawal
                      fee_summary:
                        components:
                          - amount:
                              currency: USDC
                              value: "1.00"
                            kind: network_fee
                        total:
                          currency: USDC
                          value: "1.00"
                      fill_rate: null
                      occurred_at: 2026-05-01T10:00:00Z
                      operation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      principal_amount:
                        currency: USDC
                        value: "250.00"
                      scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      status: settled
                    event_type: operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    metadata: null
                    occurred_at: 2026-05-01T10:00:00Z
                    partition_key: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    published_at: 2026-05-01T10:00:00Z
                    resource: event
                    schema_version: 1
                    scope_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    trace_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: events.get
      x-required-capability:
        - events.read
  /events/{event_id}/replay:
    post:
      description: Schedules webhook deliveries for a stored event. Omit
        `subscription_ids` to use matching subscriptions; tenant-paused
        subscriptions are excluded, while deliveries for paused platform-managed
        subscriptions are held until reactivation. An existing pending or
        retrying series is reused; a terminal series can produce a new delivery.
        Unknown, inactive or out-of-scope explicit `subscription_ids` are
        ignored; compare the returned `targeted_subscription_ids` with the
        requested list. A named target that cannot receive the event class
        returns 400 invalid_request with
        data.reason=event_type_not_subscribable; for public events, a
        tenant-created target can be selected even when its ordinary event
        filter does not match. `targeted_subscription_ids` is null when no
        explicit list was supplied.
      summary: Replay event to webhook subscriptions
      tags:
        - Distribution
        - Events
      security:
        - BearerAuth: []
      parameters:
        - name: event_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              subscription_ids:
                - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              type: object
              additionalProperties: false
              properties:
                subscription_ids:
                  type: array
                  items:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
              examples:
                - subscription_ids:
                    - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                accepted: true
                replayed_event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                targeted_subscription_ids:
                  - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - accepted
                  - replayed_event_id
                  - targeted_subscription_ids
                type: object
                additionalProperties: false
                properties:
                  accepted:
                    type: boolean
                    const: true
                  replayed_event_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  targeted_subscription_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                      - type: "null"
                examples:
                  - accepted: true
                    replayed_event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    targeted_subscription_ids:
                      - b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: events.replay
      x-required-capability:
        - events.read
        - webhooks.manage
  /events/types:
    get:
      description: Returns the canonical public webhook event catalog accepted by
        event filters and webhook subscriptions.
      summary: List webhook event types
      tags:
        - Distribution
        - Events
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - domain: operations
                    event_type: operations.withdrawal.settled.v1
                    resource: withdrawal
                    schema_version: 1
                    source_package: "@yh/operation-flow-contracts"
                    verb: settled
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - event_type
                        - domain
                        - resource
                        - verb
                        - schema_version
                        - source_package
                      type: object
                      additionalProperties: false
                      properties:
                        domain:
                          type: string
                          minLength: 1
                        event_type:
                          type: string
                          enum:
                            - tenant.enterprise.admission_reviewed.v1
                            - tenant.enterprise.admitted.v1
                            - tenant.enterprise.activated.v1
                            - tenant.enterprise.updated.v1
                            - tenant.enterprise.suspended.v1
                            - tenant.enterprise.reactivated.v1
                            - tenant.enterprise.closed.v1
                            - tenant.enterprise.terminated.v1
                            - tenant.platform_operator.admitted.v1
                            - tenant.platform_operator.restricted.v1
                            - tenant.platform_operator.reactivated.v1
                            - tenant.platform_operator.offboarded.v1
                            - tenant.platform_operator.catalog_updated.v1
                            - tenant.master_account.created.v1
                            - tenant.master_account.suspended.v1
                            - tenant.master_account.closed.v1
                            - tenant.client.created.v1
                            - tenant.client.updated.v1
                            - tenant.client.suspended.v1
                            - tenant.client.reactivated.v1
                            - tenant.client.closed.v1
                            - tenant.client_account.created.v1
                            - tenant.client_account.suspended.v1
                            - tenant.client_account.reactivated.v1
                            - tenant.client_account.closed.v1
                            - ledger.transaction.posted.v1
                            - operations.withdrawal.requested.v1
                            - operations.withdrawal.admissible.v1
                            - operations.withdrawal.executing.v1
                            - operations.withdrawal.pending_approval.v1
                            - operations.withdrawal.pending_compliance.v1
                            - operations.withdrawal.approved.v1
                            - operations.withdrawal.settled.v1
                            - operations.withdrawal.failed.v1
                            - operations.withdrawal.cancelled.v1
                            - operations.conversion.requested.v1
                            - operations.conversion.admissible.v1
                            - operations.conversion.pending_approval.v1
                            - operations.conversion.pending_compliance.v1
                            - operations.conversion.approved.v1
                            - operations.conversion.settled.v1
                            - operations.conversion.failed.v1
                            - operations.conversion.cancelled.v1
                            - operations.external_settlement_conversion.pending_compliance.v1
                            - operations.internal_transfer.requested.v1
                            - operations.internal_transfer.admissible.v1
                            - operations.internal_transfer.pending_approval.v1
                            - operations.internal_transfer.pending_compliance.v1
                            - operations.internal_transfer.approved.v1
                            - operations.internal_transfer.settled.v1
                            - operations.internal_transfer.failed.v1
                            - operations.internal_transfer.cancelled.v1
                            - operations.on_ramp.requested.v1
                            - operations.on_ramp.admissible.v1
                            - operations.on_ramp.pending_approval.v1
                            - operations.on_ramp.pending_compliance.v1
                            - operations.on_ramp.approved.v1
                            - operations.on_ramp.settled.v1
                            - operations.on_ramp.failed.v1
                            - operations.on_ramp.cancelled.v1
                            - operations.off_ramp.requested.v1
                            - operations.off_ramp.admissible.v1
                            - operations.off_ramp.pending_approval.v1
                            - operations.off_ramp.pending_compliance.v1
                            - operations.off_ramp.approved.v1
                            - operations.off_ramp.settled.v1
                            - operations.off_ramp.failed.v1
                            - operations.off_ramp.cancelled.v1
                            - operations.deposit.requested.v1
                            - operations.deposit.admissible.v1
                            - operations.deposit.pending_approval.v1
                            - operations.deposit.pending_admission.v1
                            - operations.deposit.pending_compliance.v1
                            - operations.deposit.approved.v1
                            - operations.deposit.settled.v1
                            - operations.deposit.failed.v1
                            - operations.deposit.cancelled.v1
                            - rails.deposit.detected.v1
                            - rails.dispatch.acknowledged.v1
                            - rails.dispatch.rejected.v1
                            - rails.settlement.confirmed.v1
                            - kyc.verification.reviewed.v1
                            - loan.originated.v1
                            - loan.origination_failed.v1
                            - loan.margin_called.v1
                            - loan.margin_call_cleared.v1
                            - loan.liquidation_halted.v1
                            - loan.liquidated.v1
                            - loan.repaid.v1
                            - loan.extended.v1
                            - loan.closed.v1
                            - loan.force_closed.v1
                            - loan.reconciliation_discrepancy.v1
                        resource:
                          type: string
                          minLength: 1
                        schema_version:
                          type: number
                          const: 1
                        source_package:
                          type: string
                          minLength: 1
                        verb:
                          type: string
                          minLength: 1
                examples:
                  - items:
                      - domain: operations
                        event_type: operations.withdrawal.settled.v1
                        resource: withdrawal
                        schema_version: 1
                        source_package: "@yh/operation-flow-contracts"
                        verb: settled
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: events.types
      x-required-capability:
        - events.read
  /external-settlement-conversions:
    get:
      description: Externally settled conversions are conversions that can be
        connected to an external settlement source when your enterprise needs
        that settlement model. Contact your account manager for availability and
        setup details. Lists externally settled conversion operation snapshots
        for the required account_ref, with external_settlement_conversions.read
        coverage on that account. page_size defaults to 100 (1–500); pass
        next_page_token as page_token for the next page. Responses expose
        lifecycle state, requested target currency, settlement role, settlement
        currency, and binding-resolved internal settlement account only.
        Adapter-private settlement details stay behind the service boundary.
      summary: List external settlement conversions
      tags:
        - Live Operations
        - External Settlement Conversions
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    external_settlement_role: external_source_spend
                    failure_reason: null
                    family: external_settlement_conversion
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    internal_settlement_account_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: null
                    settlement_checked_at: 2026-05-01T10:00:00Z
                    settlement_currency: EUR
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - family
                        - status
                        - account_ref
                        - principal_amount
                        - fee_summary
                        - fill_rate
                        - failure_reason
                        - settled_at
                        - approval_ref
                        - subject_attribution
                        - created_at
                        - updated_at
                        - target_currency
                        - external_settlement_role
                        - settlement_currency
                        - internal_settlement_account_ref
                        - settlement_checked_at
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        approval_ref:
                          anyOf:
                            - required:
                                - approval_id
                                - reason_code
                                - expires_at
                              type: object
                              additionalProperties: false
                              properties:
                                approval_id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                expires_at:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                reason_code:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        compliance_assessment_ref:
                          anyOf:
                            - type: string
                              pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        external_settlement_role:
                          type: string
                          enum:
                            - external_source_spend
                            - external_target_disbursement
                        failure_reason:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        family:
                          type: string
                          const: external_settlement_conversion
                        fee_summary:
                          anyOf:
                            - required:
                                - components
                                - total
                              type: object
                              additionalProperties: false
                              properties:
                                components:
                                  type: array
                                  items:
                                    required:
                                      - kind
                                      - amount
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      amount:
                                        required:
                                          - value
                                          - currency
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          currency:
                                            description: Currency code (ISO-4217 or on-chain ticker)
                                            type: string
                                            pattern: ^[A-Z0-9]{1,16}$
                                          value:
                                            description: DecimalString
                                            type: string
                                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                      kind:
                                        type: string
                                        enum:
                                          - platform_fee
                                          - enterprise_fee
                                          - network_fee
                                          - spread
                                total:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        fill_rate:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        internal_settlement_account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        principal_amount:
                          required:
                            - value
                            - currency
                          type: object
                          additionalProperties: false
                          properties:
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            value:
                              description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        settled_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        settlement_checked_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        settlement_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        status:
                          type: string
                          enum:
                            - requested
                            - admissible
                            - executing
                            - pending_approval
                            - pending_admission
                            - pending_compliance
                            - executed
                            - settled
                            - ledger_visible
                            - failed
                            - cancelled
                            - partially_settled
                        subject_attribution:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                            - federation
                            - enterprise_binding
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            authenticated_principal:
                              required:
                                - id
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                tenant_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            enterprise_binding:
                              required:
                                - topology_ref
                                - tenant_type
                              type: object
                              additionalProperties: false
                              properties:
                                tenant_type:
                                  type: string
                                  enum:
                                    - enterprise
                                    - platform_operator
                                topology_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            federation:
                              anyOf:
                                - required:
                                    - issuer
                                    - external_subject
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    external_subject:
                                      type: string
                                      minLength: 1
                                    issuer:
                                      type: string
                                      minLength: 1
                                - type: "null"
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                        target_currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        approval_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        external_settlement_role: external_source_spend
                        failure_reason: null
                        family: external_settlement_conversion
                        fee_summary:
                          components:
                            - amount:
                                currency: USDC
                                value: "1.00"
                              kind: network_fee
                          total:
                            currency: USDC
                            value: "1.00"
                        fill_rate: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        internal_settlement_account_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_amount:
                          currency: EUR
                          value: "250.00"
                        settled_at: null
                        settlement_checked_at: 2026-05-01T10:00:00Z
                        settlement_currency: EUR
                        status: admissible
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        target_currency: BTC
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: external_settlement_conversions.list
      x-required-capability:
        - external_settlement_conversions.read
    post:
      description: Externally settled conversions are conversions that can be
        connected to an external settlement source when your enterprise needs
        that settlement model. Contact your account manager for availability and
        setup details. Creates an explicit externally settled conversion. The
        strict request supplies `account_ref`, `source_amount` as `{value,
        currency}`, `target_currency`, and required `external_settlement_role`;
        settlement routing is binding-resolved by the platform. The account
        schema accepts AccountRef, but this command currently requires a client
        account with a matching external-settlement binding; master-account
        input is denied with 422. `external_source_spend` resolves the source
        currency externally, while `external_target_disbursement` resolves the
        target currency externally; the role is never inferred from the asset
        class. Idempotency-Key takes precedence over optional body
        client_idempotency_key; omitting both generates a key without
        caller-controlled replay. The response is the typed operation read
        projection, not raw family parameters. Callers with an effective human
        subject must obtain confirmation via `POST /action-tokens` using action
        `external_settlement_conversion.create` plus the structured command (or
        a matching command_digest), then send X-Action-Token. Service principals
        are exempt. The public edge does not accept delegated actor-token
        exchange or on-behalf-of headers. The 202 response is read after
        creation, so the caller also needs external_settlement_conversions.read
        or operations.recovery coverage on the account to receive it; otherwise
        creation may succeed before the response read returns 404.
        Policy/settlement denial returns not_admissible (422); unavailable
        settlement facts return temporarily_unavailable (503).
      summary: Create external settlement conversion
      tags:
        - Live Operations
        - External Settlement Conversions
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/XActionToken"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              external_settlement_role: external_source_spend
              source_amount:
                currency: EUR
                value: "250.00"
              target_currency: BTC
            schema:
              required:
                - source_amount
                - target_currency
                - account_ref
                - external_settlement_role
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                client_idempotency_key:
                  type: string
                  minLength: 1
                external_settlement_role:
                  type: string
                  enum:
                    - external_source_spend
                    - external_target_disbursement
                source_amount:
                  required:
                    - value
                    - currency
                  type: object
                  additionalProperties: false
                  properties:
                    currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    value:
                      description: DecimalString
                      type: string
                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                target_currency:
                  description: Currency code (ISO-4217 or on-chain ticker)
                  type: string
                  pattern: ^[A-Z0-9]{1,16}$
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  external_settlement_role: external_source_spend
                  source_amount:
                    currency: EUR
                    value: "250.00"
                  target_currency: BTC
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                external_settlement_role: external_source_spend
                failure_reason: null
                family: external_settlement_conversion
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: network_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                internal_settlement_account_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: EUR
                  value: "250.00"
                settled_at: null
                settlement_checked_at: 2026-05-01T10:00:00Z
                settlement_currency: EUR
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                target_currency: BTC
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - target_currency
                  - external_settlement_role
                  - settlement_currency
                  - internal_settlement_account_ref
                  - settlement_checked_at
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  external_settlement_role:
                    type: string
                    enum:
                      - external_source_spend
                      - external_target_disbursement
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: external_settlement_conversion
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  internal_settlement_account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  settlement_checked_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  settlement_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  target_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    external_settlement_role: external_source_spend
                    failure_reason: null
                    family: external_settlement_conversion
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    internal_settlement_account_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: null
                    settlement_checked_at: 2026-05-01T10:00:00Z
                    settlement_currency: EUR
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeActionTokenRequired"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: external_settlement_conversions.create
      x-required-capability:
        - external_settlement_conversions.create
  /external-settlement-conversions/{external_settlement_conversion_id}:
    get:
      description: Externally settled conversions are conversions that can be
        connected to an external settlement source when your enterprise needs
        that settlement model. Contact your account manager for availability and
        setup details. Returns the typed external settlement conversion
        operation snapshot. An absent operation, another operation family, or
        missing read/recovery scope coverage returns 404. The public shape
        contains sanitized settlement-role evidence only and never raw operation
        family parameters.
      summary: Get external settlement conversion
      tags:
        - Live Operations
        - External Settlement Conversions
      security:
        - BearerAuth: []
      parameters:
        - name: external_settlement_conversion_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                external_settlement_role: external_source_spend
                failure_reason: null
                family: external_settlement_conversion
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: network_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                internal_settlement_account_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: EUR
                  value: "250.00"
                settled_at: null
                settlement_checked_at: 2026-05-01T10:00:00Z
                settlement_currency: EUR
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                target_currency: BTC
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - target_currency
                  - external_settlement_role
                  - settlement_currency
                  - internal_settlement_account_ref
                  - settlement_checked_at
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  external_settlement_role:
                    type: string
                    enum:
                      - external_source_spend
                      - external_target_disbursement
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: external_settlement_conversion
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  internal_settlement_account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  settlement_checked_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  settlement_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  target_currency:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    external_settlement_role: external_source_spend
                    failure_reason: null
                    family: external_settlement_conversion
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    internal_settlement_account_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: null
                    settlement_checked_at: 2026-05-01T10:00:00Z
                    settlement_currency: EUR
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    target_currency: BTC
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: external_settlement_conversions.get
      x-required-capability:
        - external_settlement_conversions.read
  /fee-previews:
    post:
      description: Returns a non-binding fee preview for a planned operation.
        `subject_ref` must identify a client, client account, enterprise, or
        master account within the caller's bound tenant scope (`clients/<uuid>`,
        `client-accounts/<uuid>`, `enterprises/<uuid>`, or
        `master-accounts/<uuid>`). Pricing uses `principal_amount`,
        `service_type`, and the agreements active at `requested_at` (the current
        time when omitted). `settlement_amount` is accepted but does not
        currently affect the calculation. The response is wrapped in a
        `fee_preview` envelope; no fee-specific capability is required, but
        authentication and tenant scope checks still apply.
      summary: Preview a fee
      tags:
        - Live Operations
        - Fee Previews
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              operation_type: withdrawal_crypto
              principal_amount:
                currency: USDC
                value: "100.00"
              requested_at: 2026-05-01T10:00:00Z
              service_type: withdrawal_crypto
              settlement_amount: null
              subject_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - subject_ref
                - operation_type
                - service_type
                - principal_amount
              type: object
              additionalProperties: false
              properties:
                operation_type:
                  type: string
                  enum:
                    - withdrawal_crypto
                    - withdrawal_fiat
                    - deposit_crypto
                    - deposit_fiat
                    - internal_transfer
                    - conversion
                principal_amount:
                  required:
                    - value
                    - currency
                  type: object
                  additionalProperties: false
                  properties:
                    currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    value:
                      description: DecimalString
                      type: string
                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                requested_at:
                  type: string
                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                  format: date-time
                service_type:
                  type: string
                  enum:
                    - custody
                    - conversion
                    - withdrawal_crypto
                    - withdrawal_fiat
                    - deposit_crypto
                    - deposit_fiat
                    - internal_transfer
                    - staking
                settlement_amount:
                  anyOf:
                    - required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    - type: "null"
                subject_ref:
                  type: string
                  pattern: ^(clients|client-accounts|enterprises|master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - operation_type: withdrawal_crypto
                  principal_amount:
                    currency: USDC
                    value: "100.00"
                  requested_at: 2026-05-01T10:00:00Z
                  service_type: withdrawal_crypto
                  settlement_amount: null
                  subject_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                fee_preview:
                  binding: non_binding
                  computed_at: 2026-05-01T10:00:00Z
                  enterprise_ca_version: 2
                  fee_summary:
                    components:
                      - type: platform_fee
                        amount:
                          currency: USDC
                          value: "1.00"
                        payee_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    total:
                      currency: USDC
                      value: "1.00"
                  operation_type: withdrawal_crypto
                  platform_ca_version: 1
              schema:
                required:
                  - fee_preview
                type: object
                additionalProperties: false
                properties:
                  fee_preview:
                    required:
                      - operation_type
                      - fee_summary
                      - platform_ca_version
                      - enterprise_ca_version
                      - computed_at
                      - binding
                    type: object
                    additionalProperties: false
                    properties:
                      binding:
                        type: string
                        const: non_binding
                      computed_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      enterprise_ca_version:
                        anyOf:
                          - type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                          - type: "null"
                      fee_summary:
                        required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - type
                                - amount
                                - payee_ref
                              type: object
                              additionalProperties: false
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                payee_ref:
                                  type: string
                                  pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      operation_type:
                        type: string
                        enum:
                          - withdrawal_crypto
                          - withdrawal_fiat
                          - deposit_crypto
                          - deposit_fiat
                          - internal_transfer
                          - conversion
                      platform_ca_version:
                        anyOf:
                          - type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                          - type: "null"
                examples:
                  - fee_preview:
                      binding: non_binding
                      computed_at: 2026-05-01T10:00:00Z
                      enterprise_ca_version: 2
                      fee_summary:
                        components:
                          - type: platform_fee
                            amount:
                              currency: USDC
                              value: "1.00"
                            payee_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        total:
                          currency: USDC
                          value: "1.00"
                      operation_type: withdrawal_crypto
                      platform_ca_version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: fee_previews.create
  /funding-endpoints:
    get:
      description: Lists deposit-side endpoints for the selected rail. Crypto
        endpoints route to the custody rails backend; fiat endpoints are
        delegated to `fiat-rails-service` and scoped to the supplied
        `account_ref`. On fiat resources, `fiat_routing.bank_details` carries
        the receive details a provider issues — `provider_payment_reference`
        (`required` says whether a payment without it can fail),
        `account_holder_address`, `bank_address` and `correspondent_bank` —
        always present, `null` when the provider issued none.
        `provider_payment_reference` is the provider's own reference, separate
        from the pooled ISO 11649 `reference`.
      summary: List funding endpoints
      tags:
        - Distribution
        - Funding Endpoints
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: status
          in: query
          required: false
          schema:
            description: Endpoint lifecycle filter. status=failed is valid only when
              rail_class=fiat; crypto requests with status=failed are rejected.
            type: string
            enum:
              - provisioning
              - active
              - failed
              - disabled
              - retired
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      endpoint:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      network: ethereum
                    fiat_rail: null
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    network: ethereum
                    rail_class: crypto
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: USD
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing: null
                    failure: null
                    fiat_rail: fedwire
                    fiat_routing:
                      asset: USD
                      attribution_mode: virtual_account
                      bank_details: null
                      beneficiary_name: null
                      fiat_rail: fedwire
                      reference: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail_class: fiat
                    status: provisioning
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - rail_class
                        - status
                        - account_ref
                        - created_at
                        - updated_at
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        asset:
                          anyOf:
                            - description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        crypto_routing:
                          anyOf:
                            - required:
                                - asset
                                - network
                              type: object
                              additionalProperties: false
                              properties:
                                asset:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                endpoint:
                                  required:
                                    - address
                                    - memo
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    address:
                                      type: string
                                      minLength: 1
                                      maxLength: 256
                                    memo:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                network:
                                  type: string
                                  minLength: 1
                            - type: "null"
                        failure:
                          anyOf:
                            - required:
                                - code
                                - retryable
                              type: object
                              additionalProperties: false
                              properties:
                                code:
                                  type: string
                                  enum:
                                    - party_profile_incomplete
                                    - party_not_supported
                                    - party_already_provisioned
                                    - provider_rejected
                                    - manual_review_required
                                    - provisioning_unavailable
                                retryable:
                                  type: boolean
                            - type: "null"
                        fiat_rail:
                          anyOf:
                            - type: string
                              enum:
                                - sepa_credit_transfer
                                - faster_payments
                                - swift
                                - local_bank_transfer
                                - fedwire
                            - type: "null"
                        fiat_routing:
                          anyOf:
                            - required:
                                - asset
                                - fiat_rail
                                - attribution_mode
                              type: object
                              additionalProperties: false
                              properties:
                                asset:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                attribution_mode:
                                  type: string
                                  enum:
                                    - virtual_account
                                    - payment_reference
                                bank_details:
                                  anyOf:
                                    - oneOf:
                                        - required:
                                            - scheme
                                            - iban
                                            - bic
                                            - account_holder_name
                                            - bank_name
                                            - country
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            account_holder_address:
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            account_holder_name:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            bank_address:
                                              description: Postal address of the bank that holds the account.
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            bank_name:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                - type: "null"
                                            bic:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 11
                                                - type: "null"
                                            correspondent_bank:
                                              anyOf:
                                                - required:
                                                    - name
                                                    - bic
                                                    - account_number
                                                    - address
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    name:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    account_number:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        - type: "null"
                                                    address:
                                                      anyOf:
                                                        - required:
                                                            - lines
                                                            - city
                                                            - region
                                                            - postal_code
                                                            - country
                                                          type: object
                                                          additionalProperties: false
                                                          properties:
                                                            city:
                                                              type: string
                                                              minLength: 1
                                                              maxLength: 140
                                                            country:
                                                              type: string
                                                              pattern: ^[A-Z]{2}$
                                                            lines:
                                                              type: array
                                                              items:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 140
                                                              maxItems: 4
                                                              minItems: 1
                                                            postal_code:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 32
                                                                - type: "null"
                                                            region:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 140
                                                                - type: "null"
                                                        - type: "null"
                                                    bic:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 11
                                                - type: "null"
                                            country:
                                              type: string
                                              pattern: ^[A-Z]{2}$
                                            iban:
                                              type: string
                                              minLength: 1
                                              maxLength: 34
                                            provider_payment_reference:
                                              anyOf:
                                                - required:
                                                    - value
                                                    - required
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    required:
                                                      type: boolean
                                                    value:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                - type: "null"
                                            scheme:
                                              type: string
                                              const: iban
                                        - required:
                                            - scheme
                                            - account_number
                                            - routing_codes
                                            - bic
                                            - account_holder_name
                                            - bank_name
                                            - country
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            account_holder_address:
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            account_holder_name:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            account_number:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                            account_type:
                                              description: Checking or savings. Required by some payout rails (a US domestic
                                                wire); null or absent where the
                                                rail has no such concept.
                                              anyOf:
                                                - type: string
                                                  enum:
                                                    - checking
                                                    - savings
                                                - type: "null"
                                            bank_address:
                                              description: Postal address of the bank that holds the account.
                                              anyOf:
                                                - required:
                                                    - lines
                                                    - city
                                                    - region
                                                    - postal_code
                                                    - country
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    city:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    country:
                                                      type: string
                                                      pattern: ^[A-Z]{2}$
                                                    lines:
                                                      type: array
                                                      items:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      maxItems: 4
                                                      minItems: 1
                                                    postal_code:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 32
                                                        - type: "null"
                                                    region:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        - type: "null"
                                                - type: "null"
                                            bank_name:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                - type: "null"
                                            bic:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 11
                                                - type: "null"
                                            correspondent_bank:
                                              anyOf:
                                                - required:
                                                    - name
                                                    - bic
                                                    - account_number
                                                    - address
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    name:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    account_number:
                                                      anyOf:
                                                        - type: string
                                                          minLength: 1
                                                          maxLength: 64
                                                        - type: "null"
                                                    address:
                                                      anyOf:
                                                        - required:
                                                            - lines
                                                            - city
                                                            - region
                                                            - postal_code
                                                            - country
                                                          type: object
                                                          additionalProperties: false
                                                          properties:
                                                            city:
                                                              type: string
                                                              minLength: 1
                                                              maxLength: 140
                                                            country:
                                                              type: string
                                                              pattern: ^[A-Z]{2}$
                                                            lines:
                                                              type: array
                                                              items:
                                                                type: string
                                                                minLength: 1
                                                                maxLength: 140
                                                              maxItems: 4
                                                              minItems: 1
                                                            postal_code:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 32
                                                                - type: "null"
                                                            region:
                                                              anyOf:
                                                                - type: string
                                                                  minLength: 1
                                                                  maxLength: 140
                                                                - type: "null"
                                                        - type: "null"
                                                    bic:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 11
                                                - type: "null"
                                            country:
                                              type: string
                                              pattern: ^[A-Z]{2}$
                                            provider_payment_reference:
                                              anyOf:
                                                - required:
                                                    - value
                                                    - required
                                                  type: object
                                                  additionalProperties: false
                                                  properties:
                                                    required:
                                                      type: boolean
                                                    value:
                                                      type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                - type: "null"
                                            routing_codes:
                                              type: array
                                              items:
                                                required:
                                                  - type
                                                  - value
                                                type: object
                                                additionalProperties: false
                                                properties:
                                                  type:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  value:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 64
                                              maxItems: 16
                                              minItems: 1
                                            scheme:
                                              type: string
                                              const: local_account
                                    - type: "null"
                                beneficiary_name:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                fiat_rail:
                                  type: string
                                  enum:
                                    - sepa_credit_transfer
                                    - faster_payments
                                    - swift
                                    - local_bank_transfer
                                    - fedwire
                                reference:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        network:
                          anyOf:
                            - type: string
                            - type: "null"
                        rail_class:
                          type: string
                          enum:
                            - fiat
                            - crypto
                        status:
                          type: string
                          enum:
                            - provisioning
                            - active
                            - failed
                            - disabled
                            - retired
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        asset: USDC
                        created_at: 2026-05-01T10:00:00Z
                        crypto_routing:
                          asset: USDC
                          endpoint:
                            address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                            memo: null
                          network: ethereum
                        fiat_rail: null
                        fiat_routing: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        network: ethereum
                        rail_class: crypto
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        asset: USD
                        created_at: 2026-05-01T10:00:00Z
                        crypto_routing: null
                        failure: null
                        fiat_rail: fedwire
                        fiat_routing:
                          asset: USD
                          attribution_mode: virtual_account
                          bank_details: null
                          beneficiary_name: null
                          fiat_rail: fedwire
                          reference: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail_class: fiat
                        status: provisioning
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: funding_endpoints.list
      x-required-capability:
        - funding_endpoints.read
    post:
      description: "Provisions a new deposit-side endpoint. Crypto routes to the
        custody rails backend. Fiat requests carry only `account_ref` and
        `routing`; the pooled fiat route owner is derived server-side inside
        `rails-router-service` rather than supplied in the request body, and
        provisioning is delegated to `fiat-rails-service` after the
        route-guard/availability pipeline approves the route. Two checks can
        refuse a request with `422` and `code = not_admissible` before anything
        is provisioned. First, a fiat `local_bank_transfer` request made by a
        signed-in user needs that user to have accepted the published
        payment-account terms: otherwise `data.reason` is
        `legal_acceptance_required`, or `legal_requirement_unavailable` when no
        terms are published; requests made by service accounts skip this check.
        Then the account is checked for admission, on fiat and crypto requests
        alike, before the route or its availability is resolved: the account
        must not be suspended or closed; a client account needs a verified
        client and an enterprise master account a verified enterprise, and the
        enterprise behind the account (the parent of the client, or the owner of
        the master account) must be operational and unrestricted (one still
        being admitted, offboarding, terminated or restricted is refused); a
        master account owned by a platform operator is decided on its own status
        alone. An account refused admission returns `422` with `code =
        not_admissible`, `data.reason` one of `CLIENT_NOT_VERIFIED`,
        `ENTERPRISE_NOT_VERIFIED`, `ENTERPRISE_NOT_OPERATIONAL`,
        `ENTERPRISE_RESTRICTED`, `ACCOUNT_SUSPENDED`, `ACCOUNT_CLOSED`,
        `CLIENT_SUSPENDED`, `CLIENT_CLOSED` and `data.source` naming the check
        that refused (`verification`, `lifecycle`); when admission cannot be
        checked the request returns `503 temporarily_unavailable`. Neither
        response creates an endpoint. An idempotent retry is checked again, so
        an account refused since its first request gets the refusal instead of
        the stored endpoint. A fiat route whose provider does not serve this
        kind of account holder, such as a client account on a route that issues
        accounts to companies only, is refused with `422`, `code =
        rail_not_available` and `data.reason = fiat_party_not_supported`; a
        retry cannot open it. Idempotent on the required `Idempotency-Key`
        header. On fiat resources, `fiat_routing.bank_details` carries the
        receive details a provider issues — `provider_payment_reference`
        (`required` says whether a payment without it can fail),
        `account_holder_address`, `bank_address` and `correspondent_bank` —
        always present, `null` when the provider issued none.
        `provider_payment_reference` is the provider's own reference, separate
        from the pooled ISO 11649 `reference`."
      summary: Provision funding endpoint
      tags:
        - Distribution
        - Funding Endpoints
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Client-generated key, 1-128 characters. Accepted on POST requests
            and required where marked. For the same concrete path and
            caller/subject/tenant scope, an identical body replays the original
            status and body; a different body returns 409 idempotency_conflict.
            Keep query parameters unchanged when retrying.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              rail_class: crypto
              routing:
                asset: USDC
                network: ethereum
            schema:
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  rail_class: crypto
                  routing:
                    asset: USDC
                    network: ethereum
              oneOf:
                - required:
                    - rail_class
                    - account_ref
                    - routing
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    rail_class:
                      type: string
                      const: crypto
                    routing:
                      required:
                        - asset
                        - network
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        network:
                          type: string
                          minLength: 1
                - required:
                    - rail_class
                    - account_ref
                    - routing
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    rail_class:
                      type: string
                      const: fiat
                    routing:
                      required:
                        - asset
                        - fiat_rail
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        fiat_rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  endpoint:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  network: ethereum
                fiat_rail: null
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                network: ethereum
                rail_class: crypto
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - account_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          endpoint:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  failure:
                    anyOf:
                      - required:
                          - code
                          - retryable
                        type: object
                        additionalProperties: false
                        properties:
                          code:
                            type: string
                            enum:
                              - party_profile_incomplete
                              - party_not_supported
                              - party_already_provisioned
                              - provider_rejected
                              - manual_review_required
                              - provisioning_unavailable
                          retryable:
                            type: boolean
                      - type: "null"
                  fiat_rail:
                    anyOf:
                      - type: string
                        enum:
                          - sepa_credit_transfer
                          - faster_payments
                          - swift
                          - local_bank_transfer
                          - fedwire
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - asset
                          - fiat_rail
                          - attribution_mode
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          attribution_mode:
                            type: string
                            enum:
                              - virtual_account
                              - payment_reference
                          bank_details:
                            anyOf:
                              - oneOf:
                                  - required:
                                      - scheme
                                      - iban
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      iban:
                                        type: string
                                        minLength: 1
                                        maxLength: 34
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      scheme:
                                        type: string
                                        const: iban
                                  - required:
                                      - scheme
                                      - account_number
                                      - routing_codes
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      account_number:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      account_type:
                                        description: Checking or savings. Required by some payout rails (a US domestic
                                          wire); null or absent where the rail
                                          has no such concept.
                                        anyOf:
                                          - type: string
                                            enum:
                                              - checking
                                              - savings
                                          - type: "null"
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      routing_codes:
                                        type: array
                                        items:
                                          required:
                                            - type
                                            - value
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            type:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                            value:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                        maxItems: 16
                                        minItems: 1
                                      scheme:
                                        type: string
                                        const: local_account
                              - type: "null"
                          beneficiary_name:
                            anyOf:
                              - type: string
                              - type: "null"
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          reference:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  network:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  status:
                    type: string
                    enum:
                      - provisioning
                      - active
                      - failed
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      endpoint:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      network: ethereum
                    fiat_rail: null
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    network: ethereum
                    rail_class: crypto
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: funding_endpoints.create
      x-required-capability:
        - funding_endpoints.provision
  /funding-endpoints/{funding_endpoint_id}:
    get:
      description: Reads a funding endpoint by id. The `rail_class` query parameter is
        required so edge can route directly to the selected backend. Fiat reads
        also require `account_ref` because fiat funding endpoints are
        account-scoped; they are delegated to `fiat-rails-service`, and unknown
        or out-of-scope fiat ids return `resource_not_found`. On fiat resources,
        `fiat_routing.bank_details` carries the receive details a provider
        issues — `provider_payment_reference` (`required` says whether a payment
        without it can fail), `account_holder_address`, `bank_address` and
        `correspondent_bank` — always present, `null` when the provider issued
        none. `provider_payment_reference` is the provider's own reference,
        separate from the pooled ISO 11649 `reference`.
      summary: Get funding endpoint
      tags:
        - Distribution
        - Funding Endpoints
      security:
        - BearerAuth: []
      parameters:
        - name: funding_endpoint_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  endpoint:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  network: ethereum
                fiat_rail: null
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                network: ethereum
                rail_class: crypto
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - account_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          endpoint:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  failure:
                    anyOf:
                      - required:
                          - code
                          - retryable
                        type: object
                        additionalProperties: false
                        properties:
                          code:
                            type: string
                            enum:
                              - party_profile_incomplete
                              - party_not_supported
                              - party_already_provisioned
                              - provider_rejected
                              - manual_review_required
                              - provisioning_unavailable
                          retryable:
                            type: boolean
                      - type: "null"
                  fiat_rail:
                    anyOf:
                      - type: string
                        enum:
                          - sepa_credit_transfer
                          - faster_payments
                          - swift
                          - local_bank_transfer
                          - fedwire
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - asset
                          - fiat_rail
                          - attribution_mode
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          attribution_mode:
                            type: string
                            enum:
                              - virtual_account
                              - payment_reference
                          bank_details:
                            anyOf:
                              - oneOf:
                                  - required:
                                      - scheme
                                      - iban
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      iban:
                                        type: string
                                        minLength: 1
                                        maxLength: 34
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      scheme:
                                        type: string
                                        const: iban
                                  - required:
                                      - scheme
                                      - account_number
                                      - routing_codes
                                      - bic
                                      - account_holder_name
                                      - bank_name
                                      - country
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      account_holder_address:
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      account_holder_name:
                                        type: string
                                        minLength: 1
                                        maxLength: 140
                                      account_number:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      account_type:
                                        description: Checking or savings. Required by some payout rails (a US domestic
                                          wire); null or absent where the rail
                                          has no such concept.
                                        anyOf:
                                          - type: string
                                            enum:
                                              - checking
                                              - savings
                                          - type: "null"
                                      bank_address:
                                        description: Postal address of the bank that holds the account.
                                        anyOf:
                                          - required:
                                              - lines
                                              - city
                                              - region
                                              - postal_code
                                              - country
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              city:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              country:
                                                type: string
                                                pattern: ^[A-Z]{2}$
                                              lines:
                                                type: array
                                                items:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                maxItems: 4
                                                minItems: 1
                                              postal_code:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 32
                                                  - type: "null"
                                              region:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  - type: "null"
                                          - type: "null"
                                      bank_name:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 140
                                          - type: "null"
                                      bic:
                                        anyOf:
                                          - type: string
                                            minLength: 1
                                            maxLength: 11
                                          - type: "null"
                                      correspondent_bank:
                                        anyOf:
                                          - required:
                                              - name
                                              - bic
                                              - account_number
                                              - address
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              name:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              account_number:
                                                anyOf:
                                                  - type: string
                                                    minLength: 1
                                                    maxLength: 64
                                                  - type: "null"
                                              address:
                                                anyOf:
                                                  - required:
                                                      - lines
                                                      - city
                                                      - region
                                                      - postal_code
                                                      - country
                                                    type: object
                                                    additionalProperties: false
                                                    properties:
                                                      city:
                                                        type: string
                                                        minLength: 1
                                                        maxLength: 140
                                                      country:
                                                        type: string
                                                        pattern: ^[A-Z]{2}$
                                                      lines:
                                                        type: array
                                                        items:
                                                          type: string
                                                          minLength: 1
                                                          maxLength: 140
                                                        maxItems: 4
                                                        minItems: 1
                                                      postal_code:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 32
                                                          - type: "null"
                                                      region:
                                                        anyOf:
                                                          - type: string
                                                            minLength: 1
                                                            maxLength: 140
                                                          - type: "null"
                                                  - type: "null"
                                              bic:
                                                type: string
                                                minLength: 1
                                                maxLength: 11
                                          - type: "null"
                                      country:
                                        type: string
                                        pattern: ^[A-Z]{2}$
                                      provider_payment_reference:
                                        anyOf:
                                          - required:
                                              - value
                                              - required
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              required:
                                                type: boolean
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                          - type: "null"
                                      routing_codes:
                                        type: array
                                        items:
                                          required:
                                            - type
                                            - value
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            type:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                            value:
                                              type: string
                                              minLength: 1
                                              maxLength: 64
                                        maxItems: 16
                                        minItems: 1
                                      scheme:
                                        type: string
                                        const: local_account
                              - type: "null"
                          beneficiary_name:
                            anyOf:
                              - type: string
                              - type: "null"
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          reference:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  network:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  status:
                    type: string
                    enum:
                      - provisioning
                      - active
                      - failed
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      endpoint:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      network: ethereum
                    fiat_rail: null
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    network: ethereum
                    rail_class: crypto
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: funding_endpoints.get
      x-required-capability:
        - funding_endpoints.read
  /funding-routes/readiness:
    get:
      description: "Returns active deposit fiat route candidates from the asset
        catalog, including routes blocked by commercial eligibility, feature
        flags or runtime readiness. No crypto route is returned.
        `attribution_mode` names the setup call a route takes: `virtual_account`
        through `POST /funding-endpoints`, `payment_reference` through `POST
        /deposit-instructions`, null when the route has no configured mode. A
        null mode can also mean no commercial route owner could be resolved.
        Routes are sorted by rail then currency; the complete list has no
        external pagination. Requires a bound enterprise/client operating scope:
        missing or platform bindings return 403, and an account outside the
        bound scope is hidden with 404. An unavailable route carries the reasons
        it is blocked, the same ones setup refuses it with;
        `fiat_international_verification_required` means the account holder must
        complete the international verification first;
        `fiat_party_not_supported` means the provider of the route does not
        serve this kind of account holder, so the route stays closed for this
        account."
      summary: List the deposit fiat routes of an account with their readiness
      tags:
        - Distribution
        - Funding Endpoints
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                routes:
                  - attribution_mode: virtual_account
                    availability: unavailable
                    currency: USD
                    method: fedwire
                    rail: fedwire
                    rail_class: fiat
                    reasons:
                      - code: fiat_international_verification_required
                        source: runtime
                  - attribution_mode: virtual_account
                    availability: available
                    currency: ARS
                    method: local_bank_transfer
                    rail: local_bank_transfer
                    rail_class: fiat
                    reasons: []
              schema:
                required:
                  - account_ref
                  - routes
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  routes:
                    type: array
                    items:
                      required:
                        - rail_class
                        - rail
                        - method
                        - currency
                        - attribution_mode
                        - availability
                        - reasons
                      type: object
                      additionalProperties: false
                      properties:
                        attribution_mode:
                          anyOf:
                            - type: string
                              enum:
                                - virtual_account
                                - payment_reference
                            - type: "null"
                        availability:
                          type: string
                          enum:
                            - available
                            - unavailable
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        method:
                          type: string
                          pattern: ^[a-z0-9_]+$
                        rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                        rail_class:
                          type: string
                          const: fiat
                        reasons:
                          type: array
                          items:
                            oneOf:
                              - required:
                                  - source
                                  - code
                                type: object
                                additionalProperties: false
                                properties:
                                  code:
                                    type: string
                                    enum:
                                      - asset_rail_direction_unsupported
                                  source:
                                    type: string
                                    const: technical
                              - required:
                                  - source
                                  - code
                                type: object
                                additionalProperties: false
                                properties:
                                  code:
                                    type: string
                                    enum:
                                      - service_family_ineligible
                                  source:
                                    type: string
                                    const: commercial
                              - required:
                                  - source
                                  - code
                                type: object
                                additionalProperties: false
                                properties:
                                  code:
                                    type: string
                                    enum:
                                      - crypto_route_unavailable
                                      - crypto_provider_projection_missing
                                      - crypto_provider_disabled
                                      - crypto_provider_capability_unavailable
                                      - crypto_provider_adapter_unavailable
                                      - fiat_operation_not_implemented
                                      - fiat_provider_unavailable
                                      - fiat_catalog_unsupported
                                      - fiat_provider_disabled
                                      - fiat_pooled_endpoint_missing
                                      - fiat_pooled_endpoint_inactive
                                      - fiat_unsupported_mode
                                      - fiat_unsupported_currency
                                      - fiat_unsupported_rail_method
                                      - fiat_inbound_forwarding_disabled
                                      - fiat_international_verification_required
                                      - fiat_party_not_supported
                                  source:
                                    type: string
                                    const: runtime
                              - required:
                                  - source
                                  - code
                                type: object
                                additionalProperties: false
                                properties:
                                  code:
                                    type: string
                                    enum:
                                      - service_family_disabled
                                  source:
                                    type: string
                                    const: feature_flag
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    routes:
                      - attribution_mode: virtual_account
                        availability: unavailable
                        currency: USD
                        method: fedwire
                        rail: fedwire
                        rail_class: fiat
                        reasons:
                          - code: fiat_international_verification_required
                            source: runtime
                      - attribution_mode: virtual_account
                        availability: available
                        currency: ARS
                        method: local_bank_transfer
                        rail: local_bank_transfer
                        rail_class: fiat
                        reasons: []
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: funding_routes.readiness
  /identity-providers:
    get:
      description: "Lists provider registrations in the required scope_ref workspace:
        enterprises/<uuid> or platform-operators/<uuid>. Repeat status to filter
        by multiple lifecycle states. Requires identity_providers.manage and
        visibility of the requested workspace."
      summary: List identity providers
      tags:
        - Setup
        - Identity Providers
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - suspended
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - suspended
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - allowed_clock_skew_seconds: 30
                    auto_jit_provision: false
                    claim_mapping:
                      display_name: name
                      email: email
                      external_subject: sub
                      family_name: family_name
                      given_name: given_name
                    client_id: my-oidc-client-id
                    client_secret_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    issuer_uri: https://accounts.google.com
                    jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                    link_by_verified_email: true
                    protocol: oidc
                    resource: identity_provider
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - scope_ref
                        - status
                        - protocol
                        - issuer_uri
                        - client_id
                        - claim_mapping
                        - auto_jit_provision
                        - link_by_verified_email
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        allowed_clock_skew_seconds:
                          anyOf:
                            - type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            - type: "null"
                        auto_jit_provision:
                          type: boolean
                        claim_mapping:
                          required:
                            - external_subject
                          type: object
                          additionalProperties: false
                          properties:
                            auth_context:
                              type: array
                              items:
                                required:
                                  - normalized_acr
                                type: object
                                additionalProperties: false
                                properties:
                                  normalized_acr:
                                    type: string
                                    enum:
                                      - single-factor
                                      - mfa-if-enrolled
                                      - mfa
                                  required_acr:
                                    type: string
                                    minLength: 1
                                  required_amr:
                                    type: array
                                    items:
                                      type: string
                                      minLength: 1
                                    minItems: 1
                            display_name:
                              anyOf:
                                - type: string
                                - type: "null"
                            email:
                              anyOf:
                                - type: string
                                - type: "null"
                            external_subject:
                              type: string
                              minLength: 1
                            family_name:
                              anyOf:
                                - type: string
                                - type: "null"
                            given_name:
                              anyOf:
                                - type: string
                                - type: "null"
                            required_claims:
                              type: array
                              items:
                                required:
                                  - claim
                                  - equals
                                type: object
                                additionalProperties: false
                                properties:
                                  claim:
                                    type: string
                                    minLength: 1
                                  equals:
                                    anyOf:
                                      - type: string
                                      - type: boolean
                        client_id:
                          type: string
                          minLength: 1
                        client_secret_ref:
                          anyOf:
                            - type: string
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        etag:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        issuer_uri:
                          type: string
                          format: uri
                        jwks_uri:
                          anyOf:
                            - type: string
                              format: uri
                            - type: "null"
                        last_probe_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        last_probe_ok:
                          anyOf:
                            - type: boolean
                            - type: "null"
                        link_by_verified_email:
                          type: boolean
                        protocol:
                          type: string
                          const: oidc
                        resource:
                          type: string
                          const: identity_provider
                        scope_ref:
                          type: string
                          pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - suspended
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - allowed_clock_skew_seconds: 30
                        auto_jit_provision: false
                        claim_mapping:
                          display_name: name
                          email: email
                          external_subject: sub
                          family_name: family_name
                          given_name: given_name
                        client_id: my-oidc-client-id
                        client_secret_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        issuer_uri: https://accounts.google.com
                        jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                        link_by_verified_email: true
                        protocol: oidc
                        resource: identity_provider
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: identity_providers.list
      x-required-capability:
        - identity_providers.manage
    post:
      description: "Registers a federated OIDC identity provider for an enterprise or
        platform-operator workspace. Discovery is resolved from `issuer_uri`;
        `jwks_uri` is optional and must match the discovery document when
        supplied. For an enterprise onboarded with its own identity stack
        (first-access method `enterprise_idp`) the body is `scope_ref`,
        `issuer_uri`, `client_id` and `webhook_receiver_url` only, and it
        registers that stack instead: a resumable saga (IdP row, issuer probe,
        the backend’s service account, identity and command subscriptions) that
        answers its ledger and replays missing steps on a repeat call. On
        production registration and deletion return HTTP 409 with
        code=state_conflict and data.reason=not_supported: identity providers
        are registered by seed there."
      summary: Register identity provider
      tags:
        - Setup
        - Identity Providers
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              allowed_clock_skew_seconds: 30
              auto_jit_provision: false
              claim_mapping:
                display_name: name
                email: email
                external_subject: sub
                family_name: family_name
                given_name: given_name
              client_id: my-oidc-client-id
              client_secret_ref: null
              issuer_uri: https://accounts.google.com
              jwks_uri: https://www.googleapis.com/oauth2/v3/certs
              link_by_verified_email: true
              protocol: oidc
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              examples:
                - allowed_clock_skew_seconds: 30
                  auto_jit_provision: false
                  claim_mapping:
                    display_name: name
                    email: email
                    external_subject: sub
                    family_name: family_name
                    given_name: given_name
                  client_id: my-oidc-client-id
                  client_secret_ref: null
                  issuer_uri: https://accounts.google.com
                  jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                  link_by_verified_email: true
                  protocol: oidc
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              anyOf:
                - required:
                    - scope_ref
                    - issuer_uri
                    - client_id
                    - webhook_receiver_url
                  type: object
                  additionalProperties: false
                  properties:
                    client_id:
                      type: string
                      minLength: 1
                    issuer_uri:
                      type: string
                      format: uri
                    scope_ref:
                      type: string
                      pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    webhook_receiver_url:
                      type: string
                      format: uri
                - required:
                    - scope_ref
                    - protocol
                    - issuer_uri
                    - client_id
                    - claim_mapping
                  type: object
                  additionalProperties: false
                  properties:
                    allowed_clock_skew_seconds:
                      anyOf:
                        - type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        - type: "null"
                    auto_jit_provision:
                      type: boolean
                      default: true
                    claim_mapping:
                      required:
                        - external_subject
                      type: object
                      additionalProperties: false
                      properties:
                        auth_context:
                          type: array
                          items:
                            required:
                              - normalized_acr
                            type: object
                            additionalProperties: false
                            properties:
                              normalized_acr:
                                type: string
                                enum:
                                  - single-factor
                                  - mfa-if-enrolled
                                  - mfa
                              required_acr:
                                type: string
                                minLength: 1
                              required_amr:
                                type: array
                                items:
                                  type: string
                                  minLength: 1
                                minItems: 1
                        display_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        email:
                          anyOf:
                            - type: string
                            - type: "null"
                        external_subject:
                          type: string
                          minLength: 1
                        family_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        given_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        required_claims:
                          type: array
                          items:
                            required:
                              - claim
                              - equals
                            type: object
                            additionalProperties: false
                            properties:
                              claim:
                                type: string
                                minLength: 1
                              equals:
                                anyOf:
                                  - type: string
                                  - type: boolean
                    client_id:
                      type: string
                      minLength: 1
                    client_secret_ref:
                      anyOf:
                        - type: string
                        - type: "null"
                    issuer_uri:
                      type: string
                      format: uri
                    jwks_uri:
                      anyOf:
                        - type: string
                          format: uri
                        - type: "null"
                    link_by_verified_email:
                      type: boolean
                      default: false
                    protocol:
                      type: string
                      const: oidc
                    scope_ref:
                      type: string
                      pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                allowed_clock_skew_seconds: 30
                auto_jit_provision: false
                claim_mapping:
                  display_name: name
                  email: email
                  external_subject: sub
                  family_name: family_name
                  given_name: given_name
                client_id: my-oidc-client-id
                client_secret_ref: null
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                issuer_uri: https://accounts.google.com
                jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                link_by_verified_email: true
                protocol: oidc
                resource: identity_provider
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                examples:
                  - allowed_clock_skew_seconds: 30
                    auto_jit_provision: false
                    claim_mapping:
                      display_name: name
                      email: email
                      external_subject: sub
                      family_name: family_name
                      given_name: given_name
                    client_id: my-oidc-client-id
                    client_secret_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    issuer_uri: https://accounts.google.com
                    jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                    link_by_verified_email: true
                    protocol: oidc
                    resource: identity_provider
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                anyOf:
                  - required:
                      - id
                      - resource
                      - scope_ref
                      - status
                      - protocol
                      - issuer_uri
                      - client_id
                      - claim_mapping
                      - auto_jit_provision
                      - link_by_verified_email
                      - created_at
                      - updated_at
                      - etag
                    type: object
                    additionalProperties: false
                    properties:
                      allowed_clock_skew_seconds:
                        anyOf:
                          - type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          - type: "null"
                      auto_jit_provision:
                        type: boolean
                      claim_mapping:
                        required:
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          auth_context:
                            type: array
                            items:
                              required:
                                - normalized_acr
                              type: object
                              additionalProperties: false
                              properties:
                                normalized_acr:
                                  type: string
                                  enum:
                                    - single-factor
                                    - mfa-if-enrolled
                                    - mfa
                                required_acr:
                                  type: string
                                  minLength: 1
                                required_amr:
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                  minItems: 1
                          display_name:
                            anyOf:
                              - type: string
                              - type: "null"
                          email:
                            anyOf:
                              - type: string
                              - type: "null"
                          external_subject:
                            type: string
                            minLength: 1
                          family_name:
                            anyOf:
                              - type: string
                              - type: "null"
                          given_name:
                            anyOf:
                              - type: string
                              - type: "null"
                          required_claims:
                            type: array
                            items:
                              required:
                                - claim
                                - equals
                              type: object
                              additionalProperties: false
                              properties:
                                claim:
                                  type: string
                                  minLength: 1
                                equals:
                                  anyOf:
                                    - type: string
                                    - type: boolean
                      client_id:
                        type: string
                        minLength: 1
                      client_secret_ref:
                        anyOf:
                          - type: string
                          - type: "null"
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      etag:
                        type: string
                        minLength: 1
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      issuer_uri:
                        type: string
                        format: uri
                      jwks_uri:
                        anyOf:
                          - type: string
                            format: uri
                          - type: "null"
                      last_probe_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      last_probe_ok:
                        anyOf:
                          - type: boolean
                          - type: "null"
                      link_by_verified_email:
                        type: boolean
                      protocol:
                        type: string
                        const: oidc
                      resource:
                        type: string
                        const: identity_provider
                      scope_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      status:
                        type: string
                        enum:
                          - active
                          - suspended
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                  - required:
                      - enterprise_id
                      - identity_provider_id
                      - probe_ok
                      - service_principal_id
                      - identity_subscription_id
                      - command_subscription_id
                      - ready
                      - failing_step
                      - updated_at
                    type: object
                    additionalProperties: false
                    properties:
                      command_subscription_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      enterprise_id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      failing_step:
                        anyOf:
                          - type: string
                            enum:
                              - identity_provider
                              - probe
                              - service_account
                              - identity_subscription
                              - command_subscription
                          - type: "null"
                      identity_provider_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      identity_subscription_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      probe_ok:
                        type: boolean
                      ready:
                        type: boolean
                      service_principal_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: identity_providers.create
      x-required-capability:
        - identity_providers.manage
  /identity-providers/{identity_provider_id}:
    get:
      summary: Get identity provider
      tags:
        - Setup
        - Identity Providers
      security:
        - BearerAuth: []
      parameters:
        - name: identity_provider_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                allowed_clock_skew_seconds: 30
                auto_jit_provision: false
                claim_mapping:
                  display_name: name
                  email: email
                  external_subject: sub
                  family_name: family_name
                  given_name: given_name
                client_id: my-oidc-client-id
                client_secret_ref: null
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                issuer_uri: https://accounts.google.com
                jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                link_by_verified_email: true
                protocol: oidc
                resource: identity_provider
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - status
                  - protocol
                  - issuer_uri
                  - client_id
                  - claim_mapping
                  - auto_jit_provision
                  - link_by_verified_email
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  allowed_clock_skew_seconds:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  auto_jit_provision:
                    type: boolean
                  claim_mapping:
                    required:
                      - external_subject
                    type: object
                    additionalProperties: false
                    properties:
                      auth_context:
                        type: array
                        items:
                          required:
                            - normalized_acr
                          type: object
                          additionalProperties: false
                          properties:
                            normalized_acr:
                              type: string
                              enum:
                                - single-factor
                                - mfa-if-enrolled
                                - mfa
                            required_acr:
                              type: string
                              minLength: 1
                            required_amr:
                              type: array
                              items:
                                type: string
                                minLength: 1
                              minItems: 1
                      display_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      email:
                        anyOf:
                          - type: string
                          - type: "null"
                      external_subject:
                        type: string
                        minLength: 1
                      family_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      given_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      required_claims:
                        type: array
                        items:
                          required:
                            - claim
                            - equals
                          type: object
                          additionalProperties: false
                          properties:
                            claim:
                              type: string
                              minLength: 1
                            equals:
                              anyOf:
                                - type: string
                                - type: boolean
                  client_id:
                    type: string
                    minLength: 1
                  client_secret_ref:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  issuer_uri:
                    type: string
                    format: uri
                  jwks_uri:
                    anyOf:
                      - type: string
                        format: uri
                      - type: "null"
                  last_probe_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  last_probe_ok:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  link_by_verified_email:
                    type: boolean
                  protocol:
                    type: string
                    const: oidc
                  resource:
                    type: string
                    const: identity_provider
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - allowed_clock_skew_seconds: 30
                    auto_jit_provision: false
                    claim_mapping:
                      display_name: name
                      email: email
                      external_subject: sub
                      family_name: family_name
                      given_name: given_name
                    client_id: my-oidc-client-id
                    client_secret_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    issuer_uri: https://accounts.google.com
                    jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                    link_by_verified_email: true
                    protocol: oidc
                    resource: identity_provider
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: identity_providers.get
      x-required-capability:
        - identity_providers.manage
  /identity-providers/{identity_provider_id}/delete:
    post:
      description: Deletes a suspended provider registration and returns an empty JSON
        object. Active providers must first be suspended. Enterprise
        identity-stack trust roots cannot be deleted. On production this route
        returns HTTP 409 with code=state_conflict and data.reason=not_supported;
        the same reason applies to an enterprise identity-stack deletion in
        every environment.
      summary: Delete identity provider
      tags:
        - Setup
        - Identity Providers
      security:
        - BearerAuth: []
      parameters:
        - name: identity_provider_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: issuer compromised
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - reason: issuer compromised
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example: {}
              schema:
                type: object
                additionalProperties: false
                properties: {}
                examples:
                  - {}
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: identity_providers.delete
      x-required-capability:
        - identity_providers.manage
  /identity-providers/{identity_provider_id}/reactivate:
    post:
      description: "The identity provider of an enterprise that runs its own identity
        stack is that enterprise’s trust root: only platform staff may flip it;
        an enterprise-bound caller gets HTTP 403 with
        data.reason=platform_only_for_enterprise_idp."
      summary: Reactivate identity provider
      tags:
        - Setup
        - Identity Providers
      security:
        - BearerAuth: []
      parameters:
        - name: identity_provider_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: issuer compromised
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - reason: issuer compromised
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                allowed_clock_skew_seconds: 30
                auto_jit_provision: false
                claim_mapping:
                  display_name: name
                  email: email
                  external_subject: sub
                  family_name: family_name
                  given_name: given_name
                client_id: my-oidc-client-id
                client_secret_ref: null
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                issuer_uri: https://accounts.google.com
                jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                link_by_verified_email: true
                protocol: oidc
                resource: identity_provider
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - status
                  - protocol
                  - issuer_uri
                  - client_id
                  - claim_mapping
                  - auto_jit_provision
                  - link_by_verified_email
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  allowed_clock_skew_seconds:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  auto_jit_provision:
                    type: boolean
                  claim_mapping:
                    required:
                      - external_subject
                    type: object
                    additionalProperties: false
                    properties:
                      auth_context:
                        type: array
                        items:
                          required:
                            - normalized_acr
                          type: object
                          additionalProperties: false
                          properties:
                            normalized_acr:
                              type: string
                              enum:
                                - single-factor
                                - mfa-if-enrolled
                                - mfa
                            required_acr:
                              type: string
                              minLength: 1
                            required_amr:
                              type: array
                              items:
                                type: string
                                minLength: 1
                              minItems: 1
                      display_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      email:
                        anyOf:
                          - type: string
                          - type: "null"
                      external_subject:
                        type: string
                        minLength: 1
                      family_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      given_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      required_claims:
                        type: array
                        items:
                          required:
                            - claim
                            - equals
                          type: object
                          additionalProperties: false
                          properties:
                            claim:
                              type: string
                              minLength: 1
                            equals:
                              anyOf:
                                - type: string
                                - type: boolean
                  client_id:
                    type: string
                    minLength: 1
                  client_secret_ref:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  issuer_uri:
                    type: string
                    format: uri
                  jwks_uri:
                    anyOf:
                      - type: string
                        format: uri
                      - type: "null"
                  last_probe_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  last_probe_ok:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  link_by_verified_email:
                    type: boolean
                  protocol:
                    type: string
                    const: oidc
                  resource:
                    type: string
                    const: identity_provider
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - allowed_clock_skew_seconds: 30
                    auto_jit_provision: false
                    claim_mapping:
                      display_name: name
                      email: email
                      external_subject: sub
                      family_name: family_name
                      given_name: given_name
                    client_id: my-oidc-client-id
                    client_secret_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    issuer_uri: https://accounts.google.com
                    jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                    link_by_verified_email: true
                    protocol: oidc
                    resource: identity_provider
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: identity_providers.reactivate
      x-required-capability:
        - identity_providers.manage
  /identity-providers/{identity_provider_id}/suspend:
    post:
      description: "The identity provider of an enterprise that runs its own identity
        stack is that enterprise’s trust root: only platform staff may flip it;
        an enterprise-bound caller gets HTTP 403 with
        data.reason=platform_only_for_enterprise_idp."
      summary: Suspend identity provider
      tags:
        - Setup
        - Identity Providers
      security:
        - BearerAuth: []
      parameters:
        - name: identity_provider_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: issuer compromised
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - reason: issuer compromised
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                allowed_clock_skew_seconds: 30
                auto_jit_provision: false
                claim_mapping:
                  display_name: name
                  email: email
                  external_subject: sub
                  family_name: family_name
                  given_name: given_name
                client_id: my-oidc-client-id
                client_secret_ref: null
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                issuer_uri: https://accounts.google.com
                jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                link_by_verified_email: true
                protocol: oidc
                resource: identity_provider
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: suspended
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - status
                  - protocol
                  - issuer_uri
                  - client_id
                  - claim_mapping
                  - auto_jit_provision
                  - link_by_verified_email
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  allowed_clock_skew_seconds:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  auto_jit_provision:
                    type: boolean
                  claim_mapping:
                    required:
                      - external_subject
                    type: object
                    additionalProperties: false
                    properties:
                      auth_context:
                        type: array
                        items:
                          required:
                            - normalized_acr
                          type: object
                          additionalProperties: false
                          properties:
                            normalized_acr:
                              type: string
                              enum:
                                - single-factor
                                - mfa-if-enrolled
                                - mfa
                            required_acr:
                              type: string
                              minLength: 1
                            required_amr:
                              type: array
                              items:
                                type: string
                                minLength: 1
                              minItems: 1
                      display_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      email:
                        anyOf:
                          - type: string
                          - type: "null"
                      external_subject:
                        type: string
                        minLength: 1
                      family_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      given_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      required_claims:
                        type: array
                        items:
                          required:
                            - claim
                            - equals
                          type: object
                          additionalProperties: false
                          properties:
                            claim:
                              type: string
                              minLength: 1
                            equals:
                              anyOf:
                                - type: string
                                - type: boolean
                  client_id:
                    type: string
                    minLength: 1
                  client_secret_ref:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  issuer_uri:
                    type: string
                    format: uri
                  jwks_uri:
                    anyOf:
                      - type: string
                        format: uri
                      - type: "null"
                  last_probe_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  last_probe_ok:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  link_by_verified_email:
                    type: boolean
                  protocol:
                    type: string
                    const: oidc
                  resource:
                    type: string
                    const: identity_provider
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - allowed_clock_skew_seconds: 30
                    auto_jit_provision: false
                    claim_mapping:
                      display_name: name
                      email: email
                      external_subject: sub
                      family_name: family_name
                      given_name: given_name
                    client_id: my-oidc-client-id
                    client_secret_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    issuer_uri: https://accounts.google.com
                    jwks_uri: https://www.googleapis.com/oauth2/v3/certs
                    link_by_verified_email: true
                    protocol: oidc
                    resource: identity_provider
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: suspended
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: identity_providers.suspend
      x-required-capability:
        - identity_providers.manage
  /internal-transfers:
    get:
      summary: List internal transfers
      tags:
        - Live Operations
        - Internal Transfers
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: internal_transfer
                    family_params:
                      amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: platform_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: 2026-05-01T10:00:00Z
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      anyOf:
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - target_currency
                            - leg_attempt_id
                            - conversion_execution_id
                            - source_gross_amount
                            - source_principal_amount
                            - target_amount
                            - ledger_posted_target_amount
                            - applied_rate
                            - principal_transaction_id
                            - fee_transaction_ids
                            - posted_at
                            - failure_detail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            applied_rate:
                              anyOf:
                                - description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            conversion_execution_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_detail:
                              anyOf:
                                - required:
                                    - stage
                                    - reason_code
                                    - retryable
                                    - failed_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    failed_at:
                                      anyOf:
                                        - anyOf:
                                            - type: string
                                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                              format: date-time
                                            - type: string
                                              format: date-time
                                        - type: "null"
                                    reason_code:
                                      type: string
                                      pattern: ^[a-z0-9_.:-]+$
                                      minLength: 1
                                      maxLength: 128
                                    retryable:
                                      anyOf:
                                        - type: boolean
                                        - type: "null"
                                    stage:
                                      type: string
                                      enum:
                                        - pre_execution
                                        - execution
                                        - post_fill
                                        - ledger_posting
                                        - unknown
                                - type: "null"
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              const: conversion
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fee_transaction_ids:
                              anyOf:
                                - type: array
                                  items:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            ledger_posted_target_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            leg_attempt_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            posted_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            principal_transaction_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            source_gross_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            source_principal_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            target_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            target_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - target_currency
                            - external_settlement_role
                            - settlement_currency
                            - internal_settlement_account_ref
                            - settlement_checked_at
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            external_settlement_role:
                              type: string
                              enum:
                                - external_source_spend
                                - external_target_disbursement
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              const: external_settlement_conversion
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            internal_settlement_account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            settlement_checked_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            settlement_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            target_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - family_params
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            admission_hold_reason:
                              anyOf:
                                - type: string
                                  enum:
                                    - CLIENT_NOT_VERIFIED
                                    - ENTERPRISE_NOT_VERIFIED
                                    - ENTERPRISE_NOT_OPERATIONAL
                                    - ENTERPRISE_RESTRICTED
                                    - ACCOUNT_SUSPENDED
                                    - ACCOUNT_CLOSED
                                    - CLIENT_SUSPENDED
                                    - CLIENT_CLOSED
                                - type: "null"
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              enum:
                                - deposit
                                - withdrawal
                                - internal_transfer
                                - on_ramp
                                - off_ramp
                                - loan_origination
                                - loan_repayment
                                - loan_liquidation
                                - loan_closing
                                - loan_extension
                            family_params:
                              type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        approval_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        failure_reason: null
                        family: internal_transfer
                        family_params:
                          amount:
                            currency: USDC
                            value: "250.00"
                          source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        fee_summary:
                          components:
                            - amount:
                                currency: USDC
                                value: "1.00"
                              kind: platform_fee
                          total:
                            currency: USDC
                            value: "1.00"
                        fill_rate: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_amount:
                          currency: USDC
                          value: "250.00"
                        settled_at: 2026-05-01T10:00:00Z
                        status: settled
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: internal_transfers.list
      x-required-capability:
        - internal_transfers.read
    post:
      description: Initiates an internal transfer between two accounts inside the same
        tenant. Supply `Idempotency-Key` or body `client_idempotency_key` for
        idempotent retries; the header takes precedence. If both are omitted, a
        fresh key is generated and retries create separate operations. `amount`
        is a positive monetary value such as
        `{"value":"250.00","currency":"USDC"}`. The source and target accounts
        must differ.
      summary: Create internal transfer
      tags:
        - Live Operations
        - Internal Transfers
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              amount:
                currency: USDC
                value: "250.00"
              source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - amount
                - source_ref
                - target_ref
              type: object
              additionalProperties: false
              properties:
                amount:
                  required:
                    - value
                    - currency
                  type: object
                  additionalProperties: false
                  properties:
                    currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    value:
                      description: DecimalString
                      type: string
                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                client_idempotency_key:
                  type: string
                  minLength: 1
                source_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                target_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: internal_transfer
                family_params:
                  amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: internal_transfer
                    family_params:
                      amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: internal_transfers.create
      x-required-capability:
        - internal_transfers.create
  /internal-transfers/{internal_transfer_id}:
    get:
      summary: Get internal transfer
      tags:
        - Live Operations
        - Internal Transfers
      security:
        - BearerAuth: []
      parameters:
        - name: internal_transfer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: internal_transfer
                family_params:
                  amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: platform_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: 2026-05-01T10:00:00Z
                status: settled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: internal_transfer
                    family_params:
                      amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: platform_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: 2026-05-01T10:00:00Z
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                anyOf:
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - target_currency
                      - leg_attempt_id
                      - conversion_execution_id
                      - source_gross_amount
                      - source_principal_amount
                      - target_amount
                      - ledger_posted_target_amount
                      - applied_rate
                      - principal_transaction_id
                      - fee_transaction_ids
                      - posted_at
                      - failure_detail
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      applied_rate:
                        anyOf:
                          - description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      conversion_execution_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_detail:
                        anyOf:
                          - required:
                              - stage
                              - reason_code
                              - retryable
                              - failed_at
                            type: object
                            additionalProperties: false
                            properties:
                              failed_at:
                                anyOf:
                                  - anyOf:
                                      - type: string
                                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                        format: date-time
                                      - type: string
                                        format: date-time
                                  - type: "null"
                              reason_code:
                                type: string
                                pattern: ^[a-z0-9_.:-]+$
                                minLength: 1
                                maxLength: 128
                              retryable:
                                anyOf:
                                  - type: boolean
                                  - type: "null"
                              stage:
                                type: string
                                enum:
                                  - pre_execution
                                  - execution
                                  - post_fill
                                  - ledger_posting
                                  - unknown
                          - type: "null"
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        const: conversion
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fee_transaction_ids:
                        anyOf:
                          - type: array
                            items:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      ledger_posted_target_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      leg_attempt_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      posted_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      principal_transaction_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      source_gross_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      source_principal_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      target_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      target_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - target_currency
                      - external_settlement_role
                      - settlement_currency
                      - internal_settlement_account_ref
                      - settlement_checked_at
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      external_settlement_role:
                        type: string
                        enum:
                          - external_source_spend
                          - external_target_disbursement
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        const: external_settlement_conversion
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      internal_settlement_account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      settlement_checked_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      settlement_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      target_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - family_params
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      admission_hold_reason:
                        anyOf:
                          - type: string
                            enum:
                              - CLIENT_NOT_VERIFIED
                              - ENTERPRISE_NOT_VERIFIED
                              - ENTERPRISE_NOT_OPERATIONAL
                              - ENTERPRISE_RESTRICTED
                              - ACCOUNT_SUSPENDED
                              - ACCOUNT_CLOSED
                              - CLIENT_SUSPENDED
                              - CLIENT_CLOSED
                          - type: "null"
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        enum:
                          - deposit
                          - withdrawal
                          - internal_transfer
                          - on_ramp
                          - off_ramp
                          - loan_origination
                          - loan_repayment
                          - loan_liquidation
                          - loan_closing
                          - loan_extension
                      family_params:
                        type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: internal_transfers.get
      x-required-capability:
        - internal_transfers.read
  /internal-transfers/{internal_transfer_id}/cancel:
    post:
      summary: Cancel internal transfer
      tags:
        - Live Operations
        - Internal Transfers
      security:
        - BearerAuth: []
      parameters:
        - name: internal_transfer_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: internal_transfer
                family_params:
                  amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: cancelled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: internal_transfer
                    family_params:
                      amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: cancelled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: internal_transfers.cancel
      x-required-capability:
        - internal_transfers.manage
  /kyc/access-token:
    post:
      description: "Mints a short-lived WebSDK access token for the authenticated
        enterprise on the given verification stage (defaults to the first stage
        of the resolved flow). A stage behind the one the applicant is already
        on is refused with `flow_unresolved`: opening it would move the
        applicant back to a stage it has passed. The stage the applicant is on
        can always be opened again, for a resubmission."
      summary: Issue verification access token
      tags:
        - KYC
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              stage: company
            schema:
              type: object
              additionalProperties: false
              properties:
                stage:
                  type: string
                  enum:
                    - identity
                    - company
                    - signatories
                    - form_k
                    - international_account_intake
              examples:
                - stage: company
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                external_user_id: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                token: _act-sbx-jwt-eyJhbGciOiJub25lIn0...
              schema:
                required:
                  - token
                  - external_user_id
                type: object
                additionalProperties: false
                properties:
                  external_user_id:
                    type: string
                    minLength: 1
                    maxLength: 255
                  token:
                    type: string
                    minLength: 1
                examples:
                  - external_user_id: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    token: _act-sbx-jwt-eyJhbGciOiJub25lIn0...
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.access_token
      x-required-capability:
        - kyc.verify
  /kyc/clients/{client_id}/sessions:
    post:
      description: Initiates KYC/KYB onboarding for an End Client owned by the caller
        enterprise. Returns an embeddable WebSDK access token, a provider-hosted
        verification link, and the resolved stage flow. `legal_form` is required
        for company onboarding in legal-form jurisdictions (AR).
      summary: Start client verification session
      tags:
        - KYC
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            example:
              applicant_type: company
              country: AR
              legal_form: SA
            schema:
              required:
                - applicant_type
                - country
              type: object
              additionalProperties: false
              properties:
                applicant_type:
                  type: string
                  enum:
                    - individual
                    - company
                country:
                  type: string
                  minLength: 2
                  maxLength: 2
                legal_form:
                  type: string
                  enum:
                    - SA
                    - SRL
                    - SAS
                    - SH
                    - CH1_SEC_IV
                    - ASSOC_FOUND
                    - COOP
                    - SCS
                    - SCA
                    - TRUST
              examples:
                - applicant_type: company
                  country: AR
                  legal_form: SA
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                access_token: _act-sbx-jwt-eyJhbGciOiJub25lIn0...
                external_user_id: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                flow:
                  jurisdiction: AR
                  legal_form_required: false
                  legal_form_supported: true
                  stages:
                    - id: company
                verification_link: https://in.sumsub.com/websdk/p/sbx_AbCdEf123456
              schema:
                required:
                  - external_user_id
                  - access_token
                  - verification_link
                  - flow
                type: object
                additionalProperties: false
                properties:
                  access_token:
                    type: string
                    minLength: 1
                  external_user_id:
                    type: string
                    minLength: 1
                    maxLength: 255
                  flow:
                    required:
                      - jurisdiction
                      - legal_form_required
                      - legal_form_supported
                      - stages
                    type: object
                    additionalProperties: false
                    properties:
                      jurisdiction:
                        anyOf:
                          - type: string
                          - type: "null"
                      legal_form_required:
                        type: boolean
                      legal_form_supported:
                        type: boolean
                      stages:
                        type: array
                        items:
                          required:
                            - id
                          type: object
                          additionalProperties: false
                          properties:
                            id:
                              type: string
                              enum:
                                - identity
                                - company
                                - signatories
                                - form_k
                  verification_link:
                    type: string
                    minLength: 1
                    maxLength: 2048
                examples:
                  - access_token: _act-sbx-jwt-eyJhbGciOiJub25lIn0...
                    external_user_id: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    flow:
                      jurisdiction: AR
                      legal_form_required: false
                      legal_form_supported: true
                      stages:
                        - id: company
                    verification_link: https://in.sumsub.com/websdk/p/sbx_AbCdEf123456
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.clients.sessions
      x-required-capability:
        - kyc.verify
  /kyc/clients/{client_id}/status:
    get:
      description: Reads an End Client applicant's onboarding progress (stage, case
        status, review outcome), after asserting the caller enterprise owns the
        client.
      summary: Get client verification status
      tags:
        - KYC
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                outcome: approved
                stage: company
                status: completed
              schema:
                required:
                  - stage
                  - status
                  - outcome
                type: object
                additionalProperties: false
                properties:
                  outcome:
                    anyOf:
                      - type: string
                        enum:
                          - approved
                          - rejected
                          - resubmission_required
                      - type: "null"
                  stage:
                    anyOf:
                      - type: string
                        enum:
                          - identity
                          - company
                          - signatories
                          - form_k
                          - international_account_intake
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - not_started
                      - pending
                      - in_review
                      - completed
                examples:
                  - outcome: approved
                    stage: company
                    status: completed
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.clients.status
      x-required-capability:
        - kyc.verify
  /kyc/flow:
    get:
      description: Returns the ordered verification stages the authenticated
        enterprise walks through, resolved from its jurisdiction.
        `legal_form_required` signals the frontend must capture the company
        legal form (AR) before the company stage can open. After an Argentine
        legal form is captured, the AR flow contains a single `company` stage;
        it does not include `signatories` or `form_k`. Drive onboarding from the
        returned stages.
      summary: Get KYB onboarding flow
      tags:
        - KYC
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                jurisdiction: CH
                jurisdiction_selected: true
                legal_form_required: false
                legal_form_supported: false
                stages:
                  - id: company
                  - id: signatories
                  - id: form_k
              schema:
                required:
                  - jurisdiction
                  - legal_form_required
                  - legal_form_supported
                  - stages
                  - jurisdiction_selected
                type: object
                additionalProperties: false
                properties:
                  jurisdiction:
                    anyOf:
                      - type: string
                      - type: "null"
                  jurisdiction_selected:
                    type: boolean
                  legal_form_required:
                    type: boolean
                  legal_form_supported:
                    type: boolean
                  stages:
                    type: array
                    items:
                      required:
                        - id
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          enum:
                            - identity
                            - company
                            - signatories
                            - form_k
                examples:
                  - jurisdiction: CH
                    jurisdiction_selected: true
                    legal_form_required: false
                    legal_form_supported: false
                    stages:
                      - id: company
                      - id: signatories
                      - id: form_k
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.flow
      x-required-capability:
        - kyc.verify
  /kyc/form-k/prepare:
    post:
      description: "Pre-fills the Form K questionnaire with data collected during
        earlier KYB stages and advances the applicant to the `form_k` stage.
        Call before launching the WebSDK on the Form K stage, and only when
        `form_k` appears in the resolved `GET /kyc/flow` stages. The Argentine
        company flow does not require Form K. `fields_set: 0` means the
        applicant is already past Form K (on the international-account intake):
        nothing was moved or prefilled, and the Form K stage must not be
        opened."
      summary: Prepare Form K
      tags:
        - KYC
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                applicant_id: 68b1a2c3d4e5f60718293a4b
                fields_set: 5
              schema:
                required:
                  - applicant_id
                  - fields_set
                type: object
                additionalProperties: false
                properties:
                  applicant_id:
                    type: string
                  fields_set:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                examples:
                  - applicant_id: 68b1a2c3d4e5f60718293a4b
                    fields_set: 5
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.prepare
      x-required-capability:
        - kyc.verify
  /kyc/international-intake/prepare:
    post:
      description: "Sends the authenticated enterprise to the additional questionnaire
        an international account needs: website, industry, regulated activities,
        operating address, the tax-id registration (CUIT certificate in
        Argentina), the gross-income tax registration (Ingresos Brutos in
        Argentina), the certificate of good standing and the designation of
        authorities. Available only once KYB verification is complete (verified
        by the provider, and since then neither reopened for review, rejected
        nor restricted) and only in jurisdictions with an intake; never part of
        the KYB flow and never changes the verification status. Forward only: an
        applicant already on the intake is not moved again. Then launch the
        WebSDK on the `international_account_intake` stage. The response names
        the stage the applicant sits on afterwards."
      summary: Prepare international-account intake
      tags:
        - KYC
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                stage: international_account_intake
              schema:
                required:
                  - stage
                type: object
                additionalProperties: false
                properties:
                  stage:
                    anyOf:
                      - type: string
                        enum:
                          - identity
                          - company
                          - signatories
                          - form_k
                          - international_account_intake
                      - type: "null"
                examples:
                  - stage: international_account_intake
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.international_intake.prepare
      x-required-capability:
        - kyc.verify
  /kyc/jurisdiction:
    put:
      description: "Captures the registration jurisdiction the enterprise picks at the
        start of onboarding (ISO 3166-1 alpha-2). The flow endpoint prefers this
        over the placeholder jurisdiction stamped at admission, so the entry
        step decides which SumSub chain opens: 'AR' routes to the Argentine
        legal-form flow (then a legal form is required), any other code to the
        GLOBAL flow."
      summary: Set KYB registration jurisdiction
      tags:
        - KYC
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              jurisdiction: AR
            schema:
              required:
                - jurisdiction
              type: object
              additionalProperties: false
              properties:
                jurisdiction:
                  type: string
                  pattern: ^[A-Z]{2}$
                  minLength: 2
                  maxLength: 2
              examples:
                - jurisdiction: AR
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                jurisdiction: AR
              schema:
                required:
                  - jurisdiction
                type: object
                additionalProperties: false
                properties:
                  jurisdiction:
                    type: string
                examples:
                  - jurisdiction: AR
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.jurisdiction
      x-required-capability:
        - kyc.verify
  /kyc/legal-form:
    put:
      description: Captures the enterprise's company legal form (e.g. SA/SRL/SAS for
        Argentina) so the flow endpoint can resolve the matching company
        verification level.
      summary: Set company legal form
      tags:
        - KYC
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              legal_form: SA
            schema:
              required:
                - legal_form
              type: object
              additionalProperties: false
              properties:
                legal_form:
                  type: string
                  enum:
                    - SA
                    - SRL
                    - SAS
                    - SH
                    - CH1_SEC_IV
                    - ASSOC_FOUND
                    - COOP
                    - SCS
                    - SCA
                    - TRUST
              examples:
                - legal_form: SA
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                legal_form: SA
              schema:
                required:
                  - legal_form
                type: object
                additionalProperties: false
                properties:
                  legal_form:
                    type: string
                    enum:
                      - SA
                      - SRL
                      - SAS
                      - SH
                      - CH1_SEC_IV
                      - ASSOC_FOUND
                      - COOP
                      - SCS
                      - SCA
                      - TRUST
                examples:
                  - legal_form: SA
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.legal_form
      x-required-capability:
        - kyc.verify
  /kyc/status:
    get:
      description: "Reads the authenticated enterprise applicant's onboarding
        progress: the current verification stage, case status, and latest review
        outcome."
      summary: Get verification status
      tags:
        - KYC
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                outcome: approved
                stage: signatories
                status: completed
              schema:
                required:
                  - stage
                  - status
                  - outcome
                type: object
                additionalProperties: false
                properties:
                  outcome:
                    anyOf:
                      - type: string
                        enum:
                          - approved
                          - rejected
                          - resubmission_required
                      - type: "null"
                  stage:
                    anyOf:
                      - type: string
                        enum:
                          - identity
                          - company
                          - signatories
                          - form_k
                          - international_account_intake
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - not_started
                      - pending
                      - in_review
                      - completed
                examples:
                  - outcome: approved
                    stage: signatories
                    status: completed
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: kyc.status
      x-required-capability:
        - kyc.verify
  /legal/acceptances:
    post:
      description: Idempotent per document revision. Accepting a revision that is no
        longer published is rejected, because the caller displayed text that is
        not in force. Only human principals can record consent; the session
        determines subject and optional client scope. Re-accepting keeps the
        original evidence timestamp.
      summary: Record that the caller accepted legal documents
      tags:
        - Compliance
        - Legal
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              documents:
                - code: ar_cvu_terms
                  version: 2025-12-30
            schema:
              required:
                - documents
              type: object
              additionalProperties: false
              properties:
                documents:
                  type: array
                  items:
                    required:
                      - code
                      - version
                    type: object
                    additionalProperties: false
                    properties:
                      code:
                        type: string
                        pattern: ^[a-z][a-z0-9_]{2,63}$
                      version:
                        type: string
                        pattern: ^\d{4}-\d{2}-\d{2}(\.\d+)?$
                  maxItems: 20
                  minItems: 1
                locale:
                  type: string
                  pattern: ^[a-z]{2}(-[A-Z]{2})?$
              examples:
                - documents:
                    - code: ar_cvu_terms
                      version: 2025-12-30
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                items:
                  - accepted_at: 2026-08-25T12:18:18.576Z
                    code: ar_cvu_terms
                    locale: es-AR
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    subject_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    version: 2025-12-30
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - subject_ref
                        - scope_ref
                        - code
                        - version
                        - locale
                        - accepted_at
                      type: object
                      additionalProperties: false
                      properties:
                        accepted_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        code:
                          type: string
                          pattern: ^[a-z][a-z0-9_]{2,63}$
                        locale:
                          type: string
                          pattern: ^[a-z]{2}(-[A-Z]{2})?$
                        scope_ref:
                          anyOf:
                            - type: string
                              pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        subject_ref:
                          type: string
                          pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        version:
                          type: string
                          pattern: ^\d{4}-\d{2}-\d{2}(\.\d+)?$
                examples:
                  - items:
                      - accepted_at: 2026-08-25T12:18:18.576Z
                        code: ar_cvu_terms
                        locale: es-AR
                        scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        subject_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        version: 2025-12-30
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: legal.acceptances
  /legal/documents/{code}:
    get:
      description: Returns the published revision by default. Pass `version` to read
        the exact revision an earlier acceptance points at. Content is Markdown.
        Locale defaults to the deployment setting; missing translations fall
        back to that locale.
      summary: Read the text of a legal document
      tags:
        - Compliance
        - Legal
      security:
        - BearerAuth: []
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-z][a-z0-9_]{2,63}$
        - name: locale
          in: query
          required: false
          schema:
            type: string
            pattern: ^[a-z]{2}(-[A-Z]{2})?$
        - name: version
          in: query
          required: false
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}(\.\d+)?$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                code: ar_cvu_terms
                content: |-
                  # TÉRMINOS Y CONDICIONES DEL SERVICIO DE CUENTA DE PAGO (CVU)

                  …
                content_format: markdown
                jurisdiction: ARG
                locale: es-AR
                published_at: 2025-12-30T00:00:00.000Z
                title: Términos y Condiciones del Servicio de Cuenta de Pago (CVU)
                version: 2025-12-30
              schema:
                required:
                  - code
                  - version
                  - locale
                  - jurisdiction
                  - title
                  - content_format
                  - published_at
                  - content
                type: object
                additionalProperties: false
                properties:
                  code:
                    type: string
                    pattern: ^[a-z][a-z0-9_]{2,63}$
                  content:
                    type: string
                    minLength: 1
                  content_format:
                    type: string
                    const: markdown
                  jurisdiction:
                    type: string
                    pattern: ^[A-Z]{3}$
                  locale:
                    type: string
                    pattern: ^[a-z]{2}(-[A-Z]{2})?$
                  published_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  title:
                    type: string
                    minLength: 1
                    maxLength: 300
                  version:
                    type: string
                    pattern: ^\d{4}-\d{2}-\d{2}(\.\d+)?$
                examples:
                  - code: ar_cvu_terms
                    content: >-
                      # TÉRMINOS Y CONDICIONES DEL SERVICIO DE CUENTA DE PAGO
                      (CVU)


                      …
                    content_format: markdown
                    jurisdiction: ARG
                    locale: es-AR
                    published_at: 2025-12-30T00:00:00.000Z
                    title: Términos y Condiciones del Servicio de Cuenta de Pago (CVU)
                    version: 2025-12-30
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: legal.documents.get
  /legal/requirements:
    get:
      description: Resolved for the authenticated human actor against the documents
        published for the deployment default jurisdiction. Filter by `trigger`
        to answer "may this action proceed"; `pending_only=true` drops what is
        already accepted. A newer published revision makes an older acceptance
        pending again. Only human principals are supported; subject and optional
        client scope come from the session.
      summary: List the legal documents the caller must accept
      tags:
        - Compliance
        - Legal
      security:
        - BearerAuth: []
      parameters:
        - name: trigger
          in: query
          required: false
          schema:
            type: string
            enum:
              - onboarding
              - post_verification
              - payment_account_cvu
        - name: locale
          in: query
          required: false
          schema:
            type: string
            pattern: ^[a-z]{2}(-[A-Z]{2})?$
        - name: pending_only
          in: query
          required: false
          schema:
            type: string
            enum:
              - "true"
              - "false"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - accepted_at: null
                    accepted_version: null
                    blocking: true
                    display_order: 0
                    document:
                      code: ar_cvu_terms
                      content_format: markdown
                      jurisdiction: ARG
                      locale: es-AR
                      published_at: 2025-12-30T00:00:00.000Z
                      title: Términos y Condiciones del Servicio de Cuenta de Pago (CVU)
                      version: 2025-12-30
                    state: pending
                    trigger: payment_account_cvu
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - trigger
                        - display_order
                        - blocking
                        - document
                        - state
                        - accepted_at
                        - accepted_version
                      type: object
                      additionalProperties: false
                      properties:
                        accepted_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        accepted_version:
                          anyOf:
                            - type: string
                              pattern: ^\d{4}-\d{2}-\d{2}(\.\d+)?$
                            - type: "null"
                        blocking:
                          type: boolean
                        display_order:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        document:
                          required:
                            - code
                            - version
                            - locale
                            - jurisdiction
                            - title
                            - content_format
                            - published_at
                          type: object
                          additionalProperties: false
                          properties:
                            code:
                              type: string
                              pattern: ^[a-z][a-z0-9_]{2,63}$
                            content_format:
                              type: string
                              const: markdown
                            jurisdiction:
                              type: string
                              pattern: ^[A-Z]{3}$
                            locale:
                              type: string
                              pattern: ^[a-z]{2}(-[A-Z]{2})?$
                            published_at:
                              type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            title:
                              type: string
                              minLength: 1
                              maxLength: 300
                            version:
                              type: string
                              pattern: ^\d{4}-\d{2}-\d{2}(\.\d+)?$
                        state:
                          type: string
                          enum:
                            - pending
                            - accepted
                        trigger:
                          type: string
                          enum:
                            - onboarding
                            - post_verification
                            - payment_account_cvu
                examples:
                  - items:
                      - accepted_at: null
                        accepted_version: null
                        blocking: true
                        display_order: 0
                        document:
                          code: ar_cvu_terms
                          content_format: markdown
                          jurisdiction: ARG
                          locale: es-AR
                          published_at: 2025-12-30T00:00:00.000Z
                          title: Términos y Condiciones del Servicio de Cuenta de Pago (CVU)
                          version: 2025-12-30
                        state: pending
                        trigger: payment_account_cvu
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: legal.requirements
  /loans/{loan_id}:
    get:
      description: "Returns the caller's loan: its current debt split, its latest
        valuation and its obligations. The loans.read grant must cover the loan
        borrower account; otherwise the service returns 403."
      summary: Get a loan
      tags:
        - Live Operations
        - Loans
      security:
        - BearerAuth: []
      parameters:
        - name: loan_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                arrears_since: null
                close_reason: null
                collateral_amount:
                  currency: BTC
                  value: "2.00000000"
                collateral_held:
                  currency: BTC
                  value: "2.00000000"
                created_at: 2026-04-01T00:00:00Z
                full_payoff_amount:
                  currency: USD
                  value: "50170.6205"
                last_ltv: "0.5"
                last_valued_at: 2026-05-01T10:00:00Z
                liquidation_threshold: "0.75"
                loan_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                margin_call_since: null
                margin_call_threshold: "0.6"
                matures_at: 2027-04-01T00:00:00Z
                next_charge_at: 2026-06-01T00:00:00Z
                outstanding:
                  fees: "0"
                  interest: "120.50"
                  penalty_interest: "0"
                  principal: "50000.00"
                outstanding_total:
                  currency: USD
                  value: "50120.50"
                price: "50000"
                price_age_ms: 60000
                price_observed_at: 2026-05-01T09:59:00Z
                price_source: internal-index
                principal_amount:
                  currency: USD
                  value: "50000.00"
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - loan_id
                  - status
                  - principal_amount
                  - collateral_amount
                  - outstanding
                  - outstanding_total
                  - collateral_held
                  - last_ltv
                  - last_valued_at
                  - price
                  - price_source
                  - price_observed_at
                  - price_age_ms
                  - margin_call_threshold
                  - liquidation_threshold
                  - next_charge_at
                  - full_payoff_amount
                  - matures_at
                  - margin_call_since
                  - arrears_since
                  - close_reason
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  arrears_since:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  close_reason:
                    anyOf:
                      - type: string
                        enum:
                          - repaid
                          - matured
                          - ltv_breach
                          - offboarding
                      - type: "null"
                  collateral_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  collateral_held:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  full_payoff_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  last_ltv:
                    anyOf:
                      - description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  last_valued_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  liquidation_threshold:
                    description: DecimalString
                    type: string
                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  loan_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  margin_call_since:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  margin_call_threshold:
                    description: DecimalString
                    type: string
                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  matures_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  next_charge_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  outstanding:
                    required:
                      - fees
                      - penalty_interest
                      - interest
                      - principal
                    type: object
                    additionalProperties: false
                    properties:
                      fees:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      interest:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      penalty_interest:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      principal:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  outstanding_total:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  price:
                    anyOf:
                      - description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  price_age_ms:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: "null"
                  price_observed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  price_source:
                    anyOf:
                      - type: string
                      - type: "null"
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  status:
                    type: string
                    enum:
                      - requested
                      - awaiting_approval
                      - awaiting_compliance
                      - active
                      - denied
                      - origination_failed
                      - liquidating
                      - liquidation_halted
                      - liquidated
                      - closed
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - arrears_since: null
                    close_reason: null
                    collateral_amount:
                      currency: BTC
                      value: "2.00000000"
                    collateral_held:
                      currency: BTC
                      value: "2.00000000"
                    created_at: 2026-04-01T00:00:00Z
                    full_payoff_amount:
                      currency: USD
                      value: "50170.6205"
                    last_ltv: "0.5"
                    last_valued_at: 2026-05-01T10:00:00Z
                    liquidation_threshold: "0.75"
                    loan_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    margin_call_since: null
                    margin_call_threshold: "0.6"
                    matures_at: 2027-04-01T00:00:00Z
                    next_charge_at: 2026-06-01T00:00:00Z
                    outstanding:
                      fees: "0"
                      interest: "120.50"
                      penalty_interest: "0"
                      principal: "50000.00"
                    outstanding_total:
                      currency: USD
                      value: "50120.50"
                    price: "50000"
                    price_age_ms: 60000
                    price_observed_at: 2026-05-01T09:59:00Z
                    price_source: internal-index
                    principal_amount:
                      currency: USD
                      value: "50000.00"
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: loans.get
      x-required-capability:
        - loans.read
  /loans/{loan_id}/history:
    get:
      description: Returns a cursor-paginated page of the loan lifecycle history,
        ordered oldest first by occurrence time and transition id. page_size
        defaults to 50 and accepts 1–500. A malformed page_token returns 400.
        The loans.read grant must cover the loan borrower account.
      summary: Get a loan's lifecycle history
      tags:
        - Live Operations
        - Loans
      security:
        - BearerAuth: []
      parameters:
        - name: loan_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - correlation_ref: null
                    from_status: null
                    occurred_at: 2026-04-01T00:00:00Z
                    reason: null
                    to_status: requested
                    trigger: borrower_command
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - from_status
                        - to_status
                        - trigger
                        - reason
                        - correlation_ref
                        - occurred_at
                      type: object
                      additionalProperties: false
                      properties:
                        correlation_ref:
                          anyOf:
                            - type: string
                            - type: "null"
                        from_status:
                          anyOf:
                            - type: string
                              enum:
                                - requested
                                - awaiting_approval
                                - awaiting_compliance
                                - active
                                - denied
                                - origination_failed
                                - liquidating
                                - liquidation_halted
                                - liquidated
                                - closed
                            - type: "null"
                        occurred_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        reason:
                          anyOf:
                            - type: string
                              enum:
                                - repaid
                                - matured
                                - ltv_breach
                                - offboarding
                            - type: "null"
                        to_status:
                          type: string
                          enum:
                            - requested
                            - awaiting_approval
                            - awaiting_compliance
                            - active
                            - denied
                            - origination_failed
                            - liquidating
                            - liquidation_halted
                            - liquidated
                            - closed
                        trigger:
                          type: string
                          enum:
                            - borrower_command
                            - operator_command
                            - scheduler_tick
                            - upstream_event
                            - admissibility_verdict
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - correlation_ref: null
                        from_status: null
                        occurred_at: 2026-04-01T00:00:00Z
                        reason: null
                        to_status: requested
                        trigger: borrower_command
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: loans.history
      x-required-capability:
        - loans.read
  /master-accounts:
    get:
      description: List master accounts for a tenant scope.
        `scope_ref=enterprises/{id}` or `scope_ref=platform-operators/{id}`. The
        accounts.read grant must cover the requested tenant scope; an existing
        scope outside authority returns 403 and a missing scope returns 404.
        Repeat status to filter by multiple states. Page size defaults to 50 and
        the service caps results at 200.
      summary: List master accounts
      tags:
        - Activation
        - Master Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - suspended
                  - closed
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - suspended
                    - closed
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Primary Settlement Account
                    etag: 2026-05-01T10:00:00.000Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: master_account
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    tenant_type: enterprise
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - scope_ref
                        - tenant_type
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        display_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        etag:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        resource:
                          type: string
                          const: master_account
                        scope_ref:
                          type: string
                          pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - suspended
                            - closed
                        tenant_type:
                          type: string
                          enum:
                            - enterprise
                            - platform_operator
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - created_at: 2026-05-01T10:00:00Z
                        display_name: Primary Settlement Account
                        etag: 2026-05-01T10:00:00.000Z
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: master_account
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        tenant_type: enterprise
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: master_accounts.list
      x-required-capability:
        - accounts.read
  /master-accounts/{master_account_id}:
    get:
      description: Returns the master account with its upstream parent exposed as
        scope_ref. Missing accounts and accounts outside the accounts.read grant
        return 404.
      summary: Get master account
      tags:
        - Activation
        - Master Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: master_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Primary Settlement Account
                etag: 2026-05-01T10:00:00.000Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: master_account
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                tenant_type: enterprise
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - tenant_type
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  resource:
                    type: string
                    const: master_account
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - closed
                  tenant_type:
                    type: string
                    enum:
                      - enterprise
                      - platform_operator
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Primary Settlement Account
                    etag: 2026-05-01T10:00:00.000Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: master_account
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    tenant_type: enterprise
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: master_accounts.get
      x-required-capability:
        - accounts.read
  /master-accounts/{master_account_id}/balances:
    get:
      description: "Returns balances for a master account. Pass `?asset=USDC` to fetch
        a single balance; an omitted or empty asset returns the assets with
        operating or withdrawal-hold ledger rows. A requested asset without a
        matching ledger position returns 404. The response preserves ledger
        availability semantics: `available` excludes held funds, while `held`
        and `total` remain explicit and total = available + held. Internal
        conversion holds are excluded from these public totals. The
        accounts.read grant must cover the account or the call returns 404."
      summary: Get master-account balances
      tags:
        - Settlement
        - Balances
      security:
        - BearerAuth: []
      parameters:
        - name: master_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: asset
          in: query
          required: false
          schema:
            anyOf:
              - description: Currency code (ISO-4217 or on-chain ticker)
                type: string
                pattern: ^[A-Z0-9]{1,16}$
              - type: string
                const: ""
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - asset: USDC
                    available: "950.00"
                    held: "50.00"
                    overdraft_headroom: "400.00"
                    overdraft_limit: "500.00"
                    overdraft_used: "100.00"
                    owner_ref: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    owner_subtype: master_account
                    total: "1000.00"
                    updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - owner_ref
                        - owner_subtype
                        - asset
                        - available
                        - held
                        - total
                        - updated_at
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        available:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        held:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        overdraft_headroom:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        overdraft_limit:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        overdraft_used:
                          anyOf:
                            - description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        owner_ref:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        owner_subtype:
                          type: string
                          enum:
                            - master_account
                            - client_account
                            - treasury
                        total:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                examples:
                  - items:
                      - asset: USDC
                        available: "950.00"
                        held: "50.00"
                        overdraft_headroom: "400.00"
                        overdraft_limit: "500.00"
                        overdraft_used: "100.00"
                        owner_ref: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        owner_subtype: master_account
                        total: "1000.00"
                        updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: master_accounts.balances
      x-required-capability:
        - accounts.read
  /me/capabilities:
    get:
      description: "Returns the current effective RBAC projection: flat capability
        list and per-grant scope/propagation tuples. Source is the request
        context populated by AuthGuard; capabilities are resolved against
        current authority, not read from token claims. Grant anchor_kind is
        always returned, defaulting to explicit."
      summary: Get current capabilities
      tags:
        - Auth
        - Me
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                capabilities:
                  - withdrawals.create
                  - deposits.read
                  - clients.read
                context: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                scope_grants:
                  - anchor_kind: explicit
                    capabilities:
                      - withdrawals.create
                      - deposits.read
                    propagation: subtree
                    scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                subject: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                subject_kind: user
              schema:
                required:
                  - subject
                  - subject_kind
                  - context
                  - identity_source
                  - capabilities
                  - scope_grants
                type: object
                additionalProperties: false
                properties:
                  capabilities:
                    type: array
                    items:
                      type: string
                      pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                      minLength: 1
                  context:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  scope_grants:
                    type: array
                    items:
                      anyOf:
                        - required:
                            - anchor_kind
                            - scope
                            - propagation
                            - capabilities
                          type: object
                          additionalProperties: false
                          properties:
                            anchor_kind:
                              type: string
                              const: explicit
                            capabilities:
                              type: array
                              items:
                                type: string
                                pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                                minLength: 1
                            propagation:
                              type: string
                              enum:
                                - self
                                - subtree
                            scope:
                              type: string
                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        - required:
                            - anchor_kind
                            - scope
                            - propagation
                            - capabilities
                          type: object
                          additionalProperties: false
                          properties:
                            anchor_kind:
                              type: string
                              const: enterprise_wildcard
                            capabilities:
                              type: array
                              items:
                                type: string
                                pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                                minLength: 1
                            propagation:
                              type: string
                              const: subtree
                            scope:
                              type: string
                              pattern: ^(enterprises|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  subject:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  subject_kind:
                    type: string
                    enum:
                      - user
                      - service
                      - system
                examples:
                  - capabilities:
                      - withdrawals.create
                      - deposits.read
                      - clients.read
                    context: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    scope_grants:
                      - anchor_kind: explicit
                        capabilities:
                          - withdrawals.create
                          - deposits.read
                        propagation: subtree
                        scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    subject: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    subject_kind: user
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: me.capabilities
  /me/navigation:
    get:
      description: Returns UI-friendly section visibility based on the caller's
        capabilities. The frontend uses this to build the sidebar without
        embedding an RBAC matrix. Optional `?scope=` selects a
        platform-operator, enterprise or client context. Visibility comes from
        effective authority hydrated by AuthGuard, not claims embedded in the
        token. With scoped grants, capabilities are filtered by coverage of the
        selected context; an explicit context with no covered capabilities
        returns 403.
      summary: Get navigation sections
      tags:
        - Auth
        - Me
      security:
        - BearerAuth: []
      parameters:
        - name: scope
          in: query
          required: false
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                context: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                sections:
                  - section: wallet_balances
                    visibility: enabled
                  - section: treasury
                    visibility: enabled
                  - section: transactions
                    visibility: enabled
                  - section: end_clients
                    visibility: read_only
                  - section: access_control
                    visibility: hidden
                  - section: integrations
                    visibility: hidden
                subject: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - subject
                  - context
                  - sections
                type: object
                additionalProperties: false
                properties:
                  context:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  sections:
                    type: array
                    items:
                      required:
                        - section
                        - visibility
                      type: object
                      additionalProperties: false
                      properties:
                        section:
                          type: string
                          enum:
                            - wallet_balances
                            - treasury
                            - transactions
                            - end_clients
                            - access_control
                            - integrations
                        visibility:
                          type: string
                          enum:
                            - enabled
                            - read_only
                            - hidden
                  subject:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - context: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    sections:
                      - section: wallet_balances
                        visibility: enabled
                      - section: treasury
                        visibility: enabled
                      - section: transactions
                        visibility: enabled
                      - section: end_clients
                        visibility: read_only
                      - section: access_control
                        visibility: hidden
                      - section: integrations
                        visibility: hidden
                    subject: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: me.navigation
  /me/profile:
    get:
      description: Returns display metadata for the authenticated principal and its
        session-bound workspace. Requires authentication but no users.read or
        enterprises.read capability. Targets are derived exclusively from the
        verified session; arbitrary principal or workspace IDs cannot be
        supplied. Metadata lookup failures return null display fields; a bound
        workspace ref remains present. Service/system principals have null
        display name and email.
      summary: Get current session profile
      tags:
        - Auth
        - Me
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              schema:
                required:
                  - principal
                  - workspace
                type: object
                additionalProperties: false
                properties:
                  principal:
                    required:
                      - id
                      - kind
                      - display_name
                      - email
                    type: object
                    additionalProperties: false
                    properties:
                      display_name:
                        anyOf:
                          - type: string
                          - type: "null"
                      email:
                        anyOf:
                          - type: string
                            pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                            format: email
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      kind:
                        type: string
                        enum:
                          - user
                          - service
                          - system
                  workspace:
                    anyOf:
                      - required:
                          - ref
                          - display_name
                        type: object
                        additionalProperties: false
                        properties:
                          display_name:
                            anyOf:
                              - type: string
                              - type: "null"
                          ref:
                            type: string
                            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
          headers:
            Cache-Control:
              schema:
                type: string
                const: private, no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: me.profile
  /oauth/federated-sign-in/provider:
    get:
      description: Returns authorization-code flow endpoints only when the exact
        issuer and client ID are registered and active. The endpoints are read
        from the provider OIDC discovery document by identity-service. This
        public endpoint also exposes the registered workspace legal name as
        organization_name; it is null when the name lookup fails or times out.
        `end_session_endpoint` is the provider’s RP-initiated logout from the
        same discovery document, `null` when it has none (the console then
        restarts sign-in with `prompt=login&max_age=0`).
      summary: Resolve a federated sign-in provider
      tags:
        - Activation
        - Auth
      security: []
      parameters:
        - name: issuer
          in: query
          required: true
          schema:
            type: string
            format: uri
        - name: client_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                authorization_endpoint: https://idp.partner.example.com/authorize
                client_id: b2b-admin
                end_session_endpoint: https://idp.partner.example.com/logout
                issuer: https://idp.partner.example.com
                organization_name: Example Organization
                token_endpoint: https://idp.partner.example.com/token
              schema:
                required:
                  - issuer
                  - client_id
                  - authorization_endpoint
                  - token_endpoint
                type: object
                additionalProperties: false
                properties:
                  authorization_endpoint:
                    type: string
                    format: uri
                  authorization_response_iss_parameter_supported:
                    type: boolean
                  client_id:
                    type: string
                    minLength: 1
                  end_session_endpoint:
                    anyOf:
                      - type: string
                        format: uri
                      - type: "null"
                  issuer:
                    type: string
                    format: uri
                  organization_name:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  token_endpoint:
                    type: string
                    format: uri
                examples:
                  - authorization_endpoint: https://idp.partner.example.com/authorize
                    client_id: b2b-admin
                    end_session_endpoint: https://idp.partner.example.com/logout
                    issuer: https://idp.partner.example.com
                    organization_name: Example Organization
                    token_endpoint: https://idp.partner.example.com/token
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: oauth.provider
  /oauth/token:
    post:
      description: |-
        Issues a bearer access token for a service principal using `client_credentials`, or a federated human access token via `urn:ietf:params:oauth:grant-type:token-exchange`, and renews a human session with `refresh_token`. The `password` grant is not supported (`unsupported_grant_type`): human flows go through an external IdP plus token exchange. An enterprise identity backend authenticates `client_credentials` with `private_key_jwt` (RFC 7523): `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer` and a `client_assertion` signed with its issuer key, `aud` = this endpoint, no `client_secret`; `401` `invalid_client` for failed client authentication, including a suspended IdP or an assertion issued before its last suspension.

        **Refresh.** Only a direct sign-in, a `token-exchange` without client credentials, returns `refresh_token` and `session_expires_in` (whole seconds until the session ends, 12 hours after the sign-in that started it by default); the two fields are present together or not at all. A partner `token-exchange` authenticated with `client_id` and `client_secret`, and `client_credentials`, return an access token only. Renew with `grant_type=refresh_token` and `refresh_token` (`400` `invalid_request` without it). No client authentication is needed and request fields cannot change the stored identity or authentication evidence: the answer carries a new access token and the next refresh token, with the identity and authentication of the original sign-in, or of the session’s latest promotion. A refresh token is single-use and, by default, expires after an hour without renewal. Presenting a used one without its still-active successor ends the whole session. Every refused refresh answers `400` `invalid_grant`, whatever the cause: an unknown, expired, used or revoked token, or a user, identity provider or tenant MFA requirement that changed since sign-in. After it, sign in again. A `503` does not itself revoke the session, but the rotation may already have committed; recover with the persisted successor as described below.

        **Recovery after a lost response.** Before refreshing or promoting, generate a cryptographically random 256-bit successor (`yhrt_` followed by 43 base64url characters), persist it together with the current refresh token, and send it as `next_refresh_token`. Keep that pair until a response is safely stored. After a timeout, network error or retryable server error, send an ordinary `refresh_token` grant with the same pair. If rotation committed, possession of the still-active successor recovers it without another rotation or extension of the idle or absolute deadline; all session checks still run. Recovery does not apply new authentication evidence. Without a persisted successor, retrying a spent token revokes the session.

        **Promotion.** A `token-exchange` that also carries the session’s current `refresh_token` promotes that session instead of starting a new one. This is how a session answers the `insufficient_user_authentication` challenge after re-authenticating. The `subject_token` is verified as at sign-in. It must be a fresh ID token of the same person, from the same identity provider and in the same tenant, and its `auth_time` must be at most 15 minutes old. The answer is a refresh’s: a new access token carrying the new authentication, the next refresh token, and `session_expires_in` counted to the session’s unchanged end. The presented refresh token now counts as used, and access tokens issued earlier are not upgraded. A partner `token-exchange` has no session to promote. Refusals answer as a refresh does: `400` `invalid_grant` for any refused promotion (another person, an assertion without a recent `auth_time`, a replayed assertion, or an unknown, expired, used or revoked refresh token), `500` `server_error`, or `503` `temporarily_unavailable`. A used refresh token ends the session, as on refresh, but only when the assertion passes the sign-in and its `auth_time` is recent; any other refused promotion consumes nothing. An empty `refresh_token` is `400` `invalid_request`.

        **Errors.** Every refusal is `{"error": <code>, "error_description": <text>}` (RFC 6749 §5.2) with `Cache-Control: no-store`. Descriptions are fixed public messages; subject exchange may distinguish suspended providers, authentication predating suspension, missing provisioning and missing MFA. Refresh refusals do not expose the actor’s state. A promotion may also explain missing MFA. Internal reason codes are never returned.
      summary: Issue access token
      tags:
        - Activation
        - Auth
      security: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              client_secret: cs_live_abc123placeholder
              grant_type: client_credentials
            schema:
              required:
                - grant_type
              type: object
              additionalProperties: false
              properties:
                audience:
                  type: string
                client_assertion:
                  type: string
                  minLength: 1
                client_assertion_type:
                  type: string
                  const: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                    - urn:ietf:params:oauth:grant-type:token-exchange
                    - refresh_token
                next_refresh_token:
                  type: string
                  pattern: ^yhrt_[A-Za-z0-9_-]{43}$
                refresh_token:
                  type: string
                  minLength: 1
                requested_token_type:
                  type: string
                  const: urn:ietf:params:oauth:token-type:access_token
                subject_token:
                  type: string
                subject_token_type:
                  type: string
                  enum:
                    - urn:ietf:params:oauth:token-type:id_token
                    - urn:ietf:params:oauth:token-type:jwt
              examples:
                - client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  client_secret: cs_live_abc123placeholder
                  grant_type: client_credentials
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                access_token: eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiOGUyZjFhMCJ9.sig
                expires_in: 3600
                issued_token_type: urn:ietf:params:oauth:token-type:access_token
                token_type: Bearer
              schema:
                required:
                  - access_token
                  - token_type
                  - expires_in
                  - issued_token_type
                type: object
                additionalProperties: false
                properties:
                  access_token:
                    type: string
                    minLength: 1
                  expires_in:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                  issued_token_type:
                    type: string
                    const: urn:ietf:params:oauth:token-type:access_token
                  refresh_token:
                    type: string
                    minLength: 1
                  session_expires_in:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                  token_type:
                    type: string
                    const: Bearer
                examples:
                  - access_token: eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJiOGUyZjFhMCJ9.sig
                    expires_in: 3600
                    issued_token_type: urn:ietf:params:oauth:token-type:access_token
                    token_type: Bearer
        "400":
          description: The request was refused. On `/oauth/token`, `error` is
            `invalid_request` (malformed body, or a refused subject token or
            client), `invalid_grant` (every refused refresh) or
            `unsupported_grant_type`. On `/oauth/revoke` it is
            `invalid_request`.
          content:
            application/json:
              example:
                error: invalid_grant
                error_description: The authorization grant or refresh token is invalid, expired
                  or revoked.
              schema:
                required:
                  - error
                  - error_description
                type: object
                additionalProperties: false
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_request
                      - invalid_client
                      - invalid_grant
                      - unsupported_grant_type
                      - temporarily_unavailable
                      - server_error
                  error_description:
                    type: string
                examples:
                  - error: invalid_grant
                    error_description: The authorization grant or refresh token is invalid, expired
                      or revoked.
        "401":
          description: Client authentication failed (`invalid_client`).
          content:
            application/json:
              example:
                error: invalid_client
                error_description: Client authentication failed.
              schema:
                required:
                  - error
                  - error_description
                type: object
                additionalProperties: false
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_request
                      - invalid_client
                      - invalid_grant
                      - unsupported_grant_type
                      - temporarily_unavailable
                      - server_error
                  error_description:
                    type: string
                examples:
                  - error: invalid_client
                    error_description: Client authentication failed.
        "500":
          description: Unexpected server error (`server_error`).
          content:
            application/json:
              example:
                error: server_error
                error_description: The server encountered an unexpected error.
              schema:
                required:
                  - error
                  - error_description
                type: object
                additionalProperties: false
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_request
                      - invalid_client
                      - invalid_grant
                      - unsupported_grant_type
                      - temporarily_unavailable
                      - server_error
                  error_description:
                    type: string
                examples:
                  - error: server_error
                    error_description: The server encountered an unexpected error.
        "503":
          description: The service is temporarily unavailable (`temporarily_unavailable`);
            retry later.
          content:
            application/json:
              example:
                error: temporarily_unavailable
                error_description: The service is temporarily unavailable. Try again later.
              schema:
                required:
                  - error
                  - error_description
                type: object
                additionalProperties: false
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_request
                      - invalid_client
                      - invalid_grant
                      - unsupported_grant_type
                      - temporarily_unavailable
                      - server_error
                  error_description:
                    type: string
                examples:
                  - error: temporarily_unavailable
                    error_description: The service is temporarily unavailable. Try again later.
      operationId: oauth.token
  /off-ramp-sessions:
    get:
      summary: List off-ramp sessions
      tags:
        - Live Operations
        - Off-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: off_ramp
                    family_params:
                      destination_payload:
                        destination:
                          bank_coordinates:
                            account_holder_name: Acme Treasury
                            bank_name: Demo Bank
                            bic: NWBKGB2L
                            country: GB
                            iban: GB29NWBK60161331926819
                            scheme: iban
                          beneficiary_name: Acme Treasury
                          currency: EUR
                          fiat_rail: sepa_credit_transfer
                          method: bank_transfer
                          reference_hint: null
                        fiat_rail: sepa_credit_transfer
                        method: bank_transfer
                        payment_reference: RF18539007547034
                        withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_currency: EUR
                      target_rail: fiat
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      anyOf:
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - target_currency
                            - leg_attempt_id
                            - conversion_execution_id
                            - source_gross_amount
                            - source_principal_amount
                            - target_amount
                            - ledger_posted_target_amount
                            - applied_rate
                            - principal_transaction_id
                            - fee_transaction_ids
                            - posted_at
                            - failure_detail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            applied_rate:
                              anyOf:
                                - description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            conversion_execution_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_detail:
                              anyOf:
                                - required:
                                    - stage
                                    - reason_code
                                    - retryable
                                    - failed_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    failed_at:
                                      anyOf:
                                        - anyOf:
                                            - type: string
                                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                              format: date-time
                                            - type: string
                                              format: date-time
                                        - type: "null"
                                    reason_code:
                                      type: string
                                      pattern: ^[a-z0-9_.:-]+$
                                      minLength: 1
                                      maxLength: 128
                                    retryable:
                                      anyOf:
                                        - type: boolean
                                        - type: "null"
                                    stage:
                                      type: string
                                      enum:
                                        - pre_execution
                                        - execution
                                        - post_fill
                                        - ledger_posting
                                        - unknown
                                - type: "null"
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              const: conversion
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fee_transaction_ids:
                              anyOf:
                                - type: array
                                  items:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            ledger_posted_target_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            leg_attempt_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            posted_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            principal_transaction_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            source_gross_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            source_principal_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            target_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            target_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - target_currency
                            - external_settlement_role
                            - settlement_currency
                            - internal_settlement_account_ref
                            - settlement_checked_at
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            external_settlement_role:
                              type: string
                              enum:
                                - external_source_spend
                                - external_target_disbursement
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              const: external_settlement_conversion
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            internal_settlement_account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            settlement_checked_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            settlement_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            target_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - family_params
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            admission_hold_reason:
                              anyOf:
                                - type: string
                                  enum:
                                    - CLIENT_NOT_VERIFIED
                                    - ENTERPRISE_NOT_VERIFIED
                                    - ENTERPRISE_NOT_OPERATIONAL
                                    - ENTERPRISE_RESTRICTED
                                    - ACCOUNT_SUSPENDED
                                    - ACCOUNT_CLOSED
                                    - CLIENT_SUSPENDED
                                    - CLIENT_CLOSED
                                - type: "null"
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              enum:
                                - deposit
                                - withdrawal
                                - internal_transfer
                                - on_ramp
                                - off_ramp
                                - loan_origination
                                - loan_repayment
                                - loan_liquidation
                                - loan_closing
                                - loan_extension
                            family_params:
                              type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        approval_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        failure_reason: null
                        family: off_ramp
                        family_params:
                          destination_payload:
                            destination:
                              bank_coordinates:
                                account_holder_name: Acme Treasury
                                bank_name: Demo Bank
                                bic: NWBKGB2L
                                country: GB
                                iban: GB29NWBK60161331926819
                                scheme: iban
                              beneficiary_name: Acme Treasury
                              currency: EUR
                              fiat_rail: sepa_credit_transfer
                              method: bank_transfer
                              reference_hint: null
                            fiat_rail: sepa_credit_transfer
                            method: bank_transfer
                            payment_reference: RF18539007547034
                            withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          source_amount:
                            currency: USDC
                            value: "250.00"
                          source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          target_currency: EUR
                          target_rail: fiat
                        fee_summary:
                          components:
                            - amount:
                                currency: USDC
                                value: "1.00"
                              kind: network_fee
                          total:
                            currency: USDC
                            value: "1.00"
                        fill_rate: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_amount:
                          currency: USDC
                          value: "250.00"
                        settled_at: null
                        status: admissible
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: off_ramp_sessions.list
      x-required-capability:
        - ramps.read
    post:
      description: Initiates an off-ramp session. `amount` is the principal to debit
        from the account; `target_currency` is the asset the recipient will
        receive; `target_rail` selects the outbound delivery rail (`fiat` or
        `crypto`), and `destination` carries the matching typed withdrawal
        destination command. Crypto commands include a nullable destination_id,
        network and strict address/memo; fiat commands must identify an existing
        stored withdrawal destination and restate its routing. Caller fiat bank
        details may include bank_address and account_type where applicable;
        provider-issued receive details are refused. An `amount` with more
        fractional digits than the catalog scale of its asset is refused with
        `400 invalid_request` and `data.reason = amount_scale_exceeded` before
        anything is held; trailing zeros do not count, and an asset the catalog
        has no scale for (including crypto assets missing scale metadata) is not
        checked. Supply `Idempotency-Key` or body `client_idempotency_key` for
        idempotent retries; the header takes precedence. If both are absent,
        edge generates a fresh key, so a retry creates another operation.
      summary: Create off-ramp session
      tags:
        - Live Operations
        - Off-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              amount:
                currency: USDC
                value: "250.00"
              destination:
                destination:
                  bank_coordinates:
                    account_holder_name: Acme Treasury
                    bank_name: Demo Bank
                    bic: NWBKGB2L
                    country: GB
                    iban: GB29NWBK60161331926819
                    scheme: iban
                  beneficiary_name: Acme Treasury
                  currency: EUR
                  fiat_rail: sepa_credit_transfer
                  method: bank_transfer
                  reference_hint: null
                fiat_rail: sepa_credit_transfer
                method: bank_transfer
                payment_reference: RF18539007547034
                route_owner_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              target_currency: EUR
              target_rail: fiat
            schema:
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  amount:
                    currency: USDC
                    value: "250.00"
                  destination:
                    destination:
                      bank_coordinates:
                        account_holder_name: Acme Treasury
                        bank_name: Demo Bank
                        bic: NWBKGB2L
                        country: GB
                        iban: GB29NWBK60161331926819
                        scheme: iban
                      beneficiary_name: Acme Treasury
                      currency: EUR
                      fiat_rail: sepa_credit_transfer
                      method: bank_transfer
                      reference_hint: null
                    fiat_rail: sepa_credit_transfer
                    method: bank_transfer
                    payment_reference: RF18539007547034
                    route_owner_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_currency: EUR
                  target_rail: fiat
              oneOf:
                - required:
                    - amount
                    - target_currency
                    - target_rail
                    - account_ref
                    - destination
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    amount:
                      required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    client_idempotency_key:
                      type: string
                      minLength: 1
                    destination:
                      required:
                        - destination_id
                        - network
                        - destination
                      type: object
                      additionalProperties: false
                      properties:
                        destination:
                          required:
                            - address
                            - memo
                          type: object
                          additionalProperties: false
                          properties:
                            address:
                              type: string
                              minLength: 1
                              maxLength: 256
                            memo:
                              anyOf:
                                - type: string
                                - type: "null"
                        destination_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        network:
                          type: string
                          minLength: 1
                    target_currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    target_rail:
                      type: string
                      const: crypto
                - required:
                    - amount
                    - target_currency
                    - target_rail
                    - account_ref
                    - destination
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    amount:
                      required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    client_idempotency_key:
                      type: string
                      minLength: 1
                    destination:
                      required:
                        - route_owner_ref
                        - withdrawal_destination_id
                        - fiat_rail
                        - method
                        - destination
                        - payment_reference
                      type: object
                      additionalProperties: false
                      properties:
                        destination:
                          required:
                            - fiat_rail
                            - method
                            - currency
                            - beneficiary_name
                            - bank_coordinates
                            - reference_hint
                          type: object
                          additionalProperties: false
                          properties:
                            bank_coordinates:
                              oneOf:
                                - required:
                                    - scheme
                                    - iban
                                    - bic
                                    - account_holder_name
                                    - bank_name
                                    - country
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    account_holder_name:
                                      type: string
                                      minLength: 1
                                      maxLength: 140
                                    bank_address:
                                      description: Postal address of the bank that holds the account.
                                      anyOf:
                                        - required:
                                            - lines
                                            - city
                                            - region
                                            - postal_code
                                            - country
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            city:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            country:
                                              type: string
                                              pattern: ^[A-Z]{2}$
                                            lines:
                                              type: array
                                              items:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              maxItems: 4
                                              minItems: 1
                                            postal_code:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 32
                                                - type: "null"
                                            region:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                - type: "null"
                                        - type: "null"
                                    bank_name:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 140
                                        - type: "null"
                                    bic:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 11
                                        - type: "null"
                                    country:
                                      type: string
                                      pattern: ^[A-Z]{2}$
                                    iban:
                                      type: string
                                      minLength: 1
                                      maxLength: 34
                                    scheme:
                                      type: string
                                      const: iban
                                - required:
                                    - scheme
                                    - account_number
                                    - routing_codes
                                    - bic
                                    - account_holder_name
                                    - bank_name
                                    - country
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    account_holder_name:
                                      type: string
                                      minLength: 1
                                      maxLength: 140
                                    account_number:
                                      type: string
                                      minLength: 1
                                      maxLength: 64
                                    account_type:
                                      description: Checking or savings. Required by some payout rails (a US domestic
                                        wire); null or absent where the rail has
                                        no such concept.
                                      anyOf:
                                        - type: string
                                          enum:
                                            - checking
                                            - savings
                                        - type: "null"
                                    bank_address:
                                      description: Postal address of the bank that holds the account.
                                      anyOf:
                                        - required:
                                            - lines
                                            - city
                                            - region
                                            - postal_code
                                            - country
                                          type: object
                                          additionalProperties: false
                                          properties:
                                            city:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            country:
                                              type: string
                                              pattern: ^[A-Z]{2}$
                                            lines:
                                              type: array
                                              items:
                                                type: string
                                                minLength: 1
                                                maxLength: 140
                                              maxItems: 4
                                              minItems: 1
                                            postal_code:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 32
                                                - type: "null"
                                            region:
                                              anyOf:
                                                - type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                - type: "null"
                                        - type: "null"
                                    bank_name:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 140
                                        - type: "null"
                                    bic:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                          maxLength: 11
                                        - type: "null"
                                    country:
                                      type: string
                                      pattern: ^[A-Z]{2}$
                                    routing_codes:
                                      type: array
                                      items:
                                        required:
                                          - type
                                          - value
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          type:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                          value:
                                            type: string
                                            minLength: 1
                                            maxLength: 64
                                      maxItems: 16
                                      minItems: 1
                                    scheme:
                                      type: string
                                      const: local_account
                            beneficiary_name:
                              type: string
                              minLength: 1
                              maxLength: 140
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            fiat_rail:
                              type: string
                              enum:
                                - sepa_credit_transfer
                                - faster_payments
                                - swift
                                - local_bank_transfer
                                - fedwire
                            method:
                              type: string
                              enum:
                                - bank_transfer
                            reference_hint:
                              anyOf:
                                - type: string
                                  minLength: 1
                                  maxLength: 140
                                - type: "null"
                        fiat_rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                        method:
                          type: string
                          enum:
                            - bank_transfer
                        payment_reference:
                          anyOf:
                            - type: string
                              minLength: 1
                              maxLength: 140
                            - type: "null"
                        route_owner_ref:
                          type: string
                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        withdrawal_destination_id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                    target_currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    target_rail:
                      type: string
                      const: fiat
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: off_ramp
                family_params:
                  destination_payload:
                    destination:
                      bank_coordinates:
                        account_holder_name: Acme Treasury
                        bank_name: Demo Bank
                        bic: NWBKGB2L
                        country: GB
                        iban: GB29NWBK60161331926819
                        scheme: iban
                      beneficiary_name: Acme Treasury
                      currency: EUR
                      fiat_rail: sepa_credit_transfer
                      method: bank_transfer
                      reference_hint: null
                    fiat_rail: sepa_credit_transfer
                    method: bank_transfer
                    payment_reference: RF18539007547034
                    withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  source_amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_currency: EUR
                  target_rail: fiat
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: off_ramp
                    family_params:
                      destination_payload:
                        destination:
                          bank_coordinates:
                            account_holder_name: Acme Treasury
                            bank_name: Demo Bank
                            bic: NWBKGB2L
                            country: GB
                            iban: GB29NWBK60161331926819
                            scheme: iban
                          beneficiary_name: Acme Treasury
                          currency: EUR
                          fiat_rail: sepa_credit_transfer
                          method: bank_transfer
                          reference_hint: null
                        fiat_rail: sepa_credit_transfer
                        method: bank_transfer
                        payment_reference: RF18539007547034
                        withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_currency: EUR
                      target_rail: fiat
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: off_ramp_sessions.create
      x-required-capability:
        - ramps.create
  /off-ramp-sessions/{session_id}:
    get:
      summary: Get off-ramp session
      tags:
        - Live Operations
        - Off-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: off_ramp
                family_params:
                  destination_payload:
                    destination:
                      bank_coordinates:
                        account_holder_name: Acme Treasury
                        bank_name: Demo Bank
                        bic: NWBKGB2L
                        country: GB
                        iban: GB29NWBK60161331926819
                        scheme: iban
                      beneficiary_name: Acme Treasury
                      currency: EUR
                      fiat_rail: sepa_credit_transfer
                      method: bank_transfer
                      reference_hint: null
                    fiat_rail: sepa_credit_transfer
                    method: bank_transfer
                    payment_reference: RF18539007547034
                    withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  source_amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_currency: EUR
                  target_rail: fiat
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: network_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: off_ramp
                    family_params:
                      destination_payload:
                        destination:
                          bank_coordinates:
                            account_holder_name: Acme Treasury
                            bank_name: Demo Bank
                            bic: NWBKGB2L
                            country: GB
                            iban: GB29NWBK60161331926819
                            scheme: iban
                          beneficiary_name: Acme Treasury
                          currency: EUR
                          fiat_rail: sepa_credit_transfer
                          method: bank_transfer
                          reference_hint: null
                        fiat_rail: sepa_credit_transfer
                        method: bank_transfer
                        payment_reference: RF18539007547034
                        withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_currency: EUR
                      target_rail: fiat
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                anyOf:
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - target_currency
                      - leg_attempt_id
                      - conversion_execution_id
                      - source_gross_amount
                      - source_principal_amount
                      - target_amount
                      - ledger_posted_target_amount
                      - applied_rate
                      - principal_transaction_id
                      - fee_transaction_ids
                      - posted_at
                      - failure_detail
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      applied_rate:
                        anyOf:
                          - description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      conversion_execution_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_detail:
                        anyOf:
                          - required:
                              - stage
                              - reason_code
                              - retryable
                              - failed_at
                            type: object
                            additionalProperties: false
                            properties:
                              failed_at:
                                anyOf:
                                  - anyOf:
                                      - type: string
                                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                        format: date-time
                                      - type: string
                                        format: date-time
                                  - type: "null"
                              reason_code:
                                type: string
                                pattern: ^[a-z0-9_.:-]+$
                                minLength: 1
                                maxLength: 128
                              retryable:
                                anyOf:
                                  - type: boolean
                                  - type: "null"
                              stage:
                                type: string
                                enum:
                                  - pre_execution
                                  - execution
                                  - post_fill
                                  - ledger_posting
                                  - unknown
                          - type: "null"
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        const: conversion
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fee_transaction_ids:
                        anyOf:
                          - type: array
                            items:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      ledger_posted_target_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      leg_attempt_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      posted_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      principal_transaction_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      source_gross_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      source_principal_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      target_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      target_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - target_currency
                      - external_settlement_role
                      - settlement_currency
                      - internal_settlement_account_ref
                      - settlement_checked_at
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      external_settlement_role:
                        type: string
                        enum:
                          - external_source_spend
                          - external_target_disbursement
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        const: external_settlement_conversion
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      internal_settlement_account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      settlement_checked_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      settlement_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      target_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - family_params
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      admission_hold_reason:
                        anyOf:
                          - type: string
                            enum:
                              - CLIENT_NOT_VERIFIED
                              - ENTERPRISE_NOT_VERIFIED
                              - ENTERPRISE_NOT_OPERATIONAL
                              - ENTERPRISE_RESTRICTED
                              - ACCOUNT_SUSPENDED
                              - ACCOUNT_CLOSED
                              - CLIENT_SUSPENDED
                              - CLIENT_CLOSED
                          - type: "null"
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        enum:
                          - deposit
                          - withdrawal
                          - internal_transfer
                          - on_ramp
                          - off_ramp
                          - loan_origination
                          - loan_repayment
                          - loan_liquidation
                          - loan_closing
                          - loan_extension
                      family_params:
                        type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: off_ramp_sessions.get
      x-required-capability:
        - ramps.read
  /off-ramp-sessions/{session_id}/cancel:
    post:
      summary: Cancel off-ramp session
      tags:
        - Live Operations
        - Off-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: off_ramp
                family_params:
                  destination_payload:
                    destination:
                      bank_coordinates:
                        account_holder_name: Acme Treasury
                        bank_name: Demo Bank
                        bic: NWBKGB2L
                        country: GB
                        iban: GB29NWBK60161331926819
                        scheme: iban
                      beneficiary_name: Acme Treasury
                      currency: EUR
                      fiat_rail: sepa_credit_transfer
                      method: bank_transfer
                      reference_hint: null
                    fiat_rail: sepa_credit_transfer
                    method: bank_transfer
                    payment_reference: RF18539007547034
                    withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  source_amount:
                    currency: USDC
                    value: "250.00"
                  source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  target_currency: EUR
                  target_rail: fiat
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: cancelled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: off_ramp
                    family_params:
                      destination_payload:
                        destination:
                          bank_coordinates:
                            account_holder_name: Acme Treasury
                            bank_name: Demo Bank
                            bic: NWBKGB2L
                            country: GB
                            iban: GB29NWBK60161331926819
                            scheme: iban
                          beneficiary_name: Acme Treasury
                          currency: EUR
                          fiat_rail: sepa_credit_transfer
                          method: bank_transfer
                          reference_hint: null
                        fiat_rail: sepa_credit_transfer
                        method: bank_transfer
                        payment_reference: RF18539007547034
                        withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: USDC
                        value: "250.00"
                      source_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      target_currency: EUR
                      target_rail: fiat
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: cancelled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: off_ramp_sessions.cancel
      x-required-capability:
        - ramps.manage
  /on-ramp-sessions:
    get:
      summary: List on-ramp sessions
      tags:
        - Live Operations
        - On-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: on_ramp
                    family_params:
                      destination_payload: {}
                      destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: EUR
                        value: "250.00"
                      source_rail: fiat
                      target_currency: USDC
                    fee_summary:
                      components:
                        - amount:
                            currency: EUR
                            value: "1.00"
                          kind: platform_fee
                      total:
                        currency: EUR
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: 2026-05-01T10:00:00Z
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      anyOf:
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - target_currency
                            - leg_attempt_id
                            - conversion_execution_id
                            - source_gross_amount
                            - source_principal_amount
                            - target_amount
                            - ledger_posted_target_amount
                            - applied_rate
                            - principal_transaction_id
                            - fee_transaction_ids
                            - posted_at
                            - failure_detail
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            applied_rate:
                              anyOf:
                                - description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            conversion_execution_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_detail:
                              anyOf:
                                - required:
                                    - stage
                                    - reason_code
                                    - retryable
                                    - failed_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    failed_at:
                                      anyOf:
                                        - anyOf:
                                            - type: string
                                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                              format: date-time
                                            - type: string
                                              format: date-time
                                        - type: "null"
                                    reason_code:
                                      type: string
                                      pattern: ^[a-z0-9_.:-]+$
                                      minLength: 1
                                      maxLength: 128
                                    retryable:
                                      anyOf:
                                        - type: boolean
                                        - type: "null"
                                    stage:
                                      type: string
                                      enum:
                                        - pre_execution
                                        - execution
                                        - post_fill
                                        - ledger_posting
                                        - unknown
                                - type: "null"
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              const: conversion
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fee_transaction_ids:
                              anyOf:
                                - type: array
                                  items:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            ledger_posted_target_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            leg_attempt_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            posted_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            principal_transaction_id:
                              anyOf:
                                - type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                - type: "null"
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            source_gross_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            source_principal_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            target_amount:
                              anyOf:
                                - required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            target_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - target_currency
                            - external_settlement_role
                            - settlement_currency
                            - internal_settlement_account_ref
                            - settlement_checked_at
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            external_settlement_role:
                              type: string
                              enum:
                                - external_source_spend
                                - external_target_disbursement
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              const: external_settlement_conversion
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            internal_settlement_account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            settlement_checked_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            settlement_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            target_currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                        - required:
                            - id
                            - family
                            - status
                            - account_ref
                            - principal_amount
                            - fee_summary
                            - fill_rate
                            - failure_reason
                            - settled_at
                            - approval_ref
                            - subject_attribution
                            - created_at
                            - updated_at
                            - family_params
                          type: object
                          additionalProperties: false
                          properties:
                            account_ref:
                              type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            admission_hold_reason:
                              anyOf:
                                - type: string
                                  enum:
                                    - CLIENT_NOT_VERIFIED
                                    - ENTERPRISE_NOT_VERIFIED
                                    - ENTERPRISE_NOT_OPERATIONAL
                                    - ENTERPRISE_RESTRICTED
                                    - ACCOUNT_SUSPENDED
                                    - ACCOUNT_CLOSED
                                    - CLIENT_SUSPENDED
                                    - CLIENT_CLOSED
                                - type: "null"
                            approval_ref:
                              anyOf:
                                - required:
                                    - approval_id
                                    - reason_code
                                    - expires_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    approval_id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    expires_at:
                                      anyOf:
                                        - type: string
                                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                          format: date-time
                                        - type: string
                                          format: date-time
                                    reason_code:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                - type: "null"
                            compliance_assessment_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            created_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_reason:
                              anyOf:
                                - type: string
                                  minLength: 1
                                - type: "null"
                            family:
                              type: string
                              enum:
                                - deposit
                                - withdrawal
                                - internal_transfer
                                - on_ramp
                                - off_ramp
                                - loan_origination
                                - loan_repayment
                                - loan_liquidation
                                - loan_closing
                                - loan_extension
                            family_params:
                              type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            fee_summary:
                              anyOf:
                                - required:
                                    - components
                                    - total
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    components:
                                      type: array
                                      items:
                                        required:
                                          - kind
                                          - amount
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          amount:
                                            required:
                                              - value
                                              - currency
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              currency:
                                                description: Currency code (ISO-4217 or on-chain ticker)
                                                type: string
                                                pattern: ^[A-Z0-9]{1,16}$
                                              value:
                                                description: DecimalString
                                                type: string
                                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                          kind:
                                            type: string
                                            enum:
                                              - platform_fee
                                              - enterprise_fee
                                              - network_fee
                                              - spread
                                    total:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                - type: "null"
                            fill_rate:
                              anyOf:
                                - type: string
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            principal_amount:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            settled_at:
                              anyOf:
                                - anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                - type: "null"
                            status:
                              type: string
                              enum:
                                - requested
                                - admissible
                                - executing
                                - pending_approval
                                - pending_admission
                                - pending_compliance
                                - executed
                                - settled
                                - ledger_visible
                                - failed
                                - cancelled
                                - partially_settled
                            subject_attribution:
                              required:
                                - authenticated_principal
                                - subject
                                - actor
                                - initiated_by
                                - approved_by
                                - identity_source
                                - federation
                                - enterprise_binding
                              type: object
                              additionalProperties: false
                              properties:
                                actor:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                approved_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                authenticated_principal:
                                  required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                enterprise_binding:
                                  required:
                                    - topology_ref
                                    - tenant_type
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    tenant_type:
                                      type: string
                                      enum:
                                        - enterprise
                                        - platform_operator
                                    topology_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                federation:
                                  anyOf:
                                    - required:
                                        - issuer
                                        - external_subject
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        external_subject:
                                          type: string
                                          minLength: 1
                                        issuer:
                                          type: string
                                          minLength: 1
                                    - type: "null"
                                identity_source:
                                  type: string
                                  enum:
                                    - platform-managed
                                    - federated
                                    - system
                                initiated_by:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                                subject:
                                  anyOf:
                                    - required:
                                        - id
                                        - kind
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        id:
                                          type: string
                                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                          format: uuid
                                        kind:
                                          type: string
                                          enum:
                                            - user
                                            - service
                                            - system
                                        tenant_ref:
                                          anyOf:
                                            - type: string
                                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                            - type: "null"
                                    - type: "null"
                            updated_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        approval_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        failure_reason: null
                        family: on_ramp
                        family_params:
                          destination_payload: {}
                          destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          source_amount:
                            currency: EUR
                            value: "250.00"
                          source_rail: fiat
                          target_currency: USDC
                        fee_summary:
                          components:
                            - amount:
                                currency: EUR
                                value: "1.00"
                              kind: platform_fee
                          total:
                            currency: EUR
                            value: "1.00"
                        fill_rate: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_amount:
                          currency: EUR
                          value: "250.00"
                        settled_at: 2026-05-01T10:00:00Z
                        status: settled
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: on_ramp_sessions.list
      x-required-capability:
        - ramps.read
    post:
      description: Initiates an on-ramp session. `amount` is the expected inbound
        principal; `target_currency` is the asset the account will receive after
        conversion; `source_rail` selects the inbound funding rail (`fiat` or
        `crypto`). `destination` is optional and defaults to an empty object; it
        uses a generic record rather than a typed funding-instruction schema.
        Supply `Idempotency-Key` or body `client_idempotency_key` for idempotent
        retries; the header takes precedence. If both are absent, edge generates
        a fresh key, so a retry creates another operation.
      summary: Create on-ramp session
      tags:
        - Live Operations
        - On-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              amount:
                currency: EUR
                value: "250.00"
              source_rail: fiat
              target_currency: USDC
            schema:
              required:
                - amount
                - target_currency
                - source_rail
                - account_ref
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                amount:
                  required:
                    - value
                    - currency
                  type: object
                  additionalProperties: false
                  properties:
                    currency:
                      description: Currency code (ISO-4217 or on-chain ticker)
                      type: string
                      pattern: ^[A-Z0-9]{1,16}$
                    value:
                      description: DecimalString
                      type: string
                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                client_idempotency_key:
                  type: string
                  minLength: 1
                destination:
                  type: object
                  additionalProperties: {}
                  propertyNames:
                    type: string
                source_rail:
                  type: string
                  enum:
                    - fiat
                    - crypto
                target_currency:
                  description: Currency code (ISO-4217 or on-chain ticker)
                  type: string
                  pattern: ^[A-Z0-9]{1,16}$
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  amount:
                    currency: EUR
                    value: "250.00"
                  source_rail: fiat
                  target_currency: USDC
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: on_ramp
                family_params:
                  destination_payload: {}
                  destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  source_amount:
                    currency: EUR
                    value: "250.00"
                  source_rail: fiat
                  target_currency: USDC
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: EUR
                  value: "250.00"
                settled_at: null
                status: admissible
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: on_ramp
                    family_params:
                      destination_payload: {}
                      destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: EUR
                        value: "250.00"
                      source_rail: fiat
                      target_currency: USDC
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: null
                    status: admissible
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: on_ramp_sessions.create
      x-required-capability:
        - ramps.create
  /on-ramp-sessions/{session_id}:
    get:
      summary: Get on-ramp session
      tags:
        - Live Operations
        - On-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: on_ramp
                family_params:
                  destination_payload: {}
                  destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  source_amount:
                    currency: EUR
                    value: "250.00"
                  source_rail: fiat
                  target_currency: USDC
                fee_summary:
                  components:
                    - amount:
                        currency: EUR
                        value: "1.00"
                      kind: platform_fee
                  total:
                    currency: EUR
                    value: "1.00"
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: EUR
                  value: "250.00"
                settled_at: 2026-05-01T10:00:00Z
                status: settled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: on_ramp
                    family_params:
                      destination_payload: {}
                      destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: EUR
                        value: "250.00"
                      source_rail: fiat
                      target_currency: USDC
                    fee_summary:
                      components:
                        - amount:
                            currency: EUR
                            value: "1.00"
                          kind: platform_fee
                      total:
                        currency: EUR
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: 2026-05-01T10:00:00Z
                    status: settled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                anyOf:
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - target_currency
                      - leg_attempt_id
                      - conversion_execution_id
                      - source_gross_amount
                      - source_principal_amount
                      - target_amount
                      - ledger_posted_target_amount
                      - applied_rate
                      - principal_transaction_id
                      - fee_transaction_ids
                      - posted_at
                      - failure_detail
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      applied_rate:
                        anyOf:
                          - description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      conversion_execution_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_detail:
                        anyOf:
                          - required:
                              - stage
                              - reason_code
                              - retryable
                              - failed_at
                            type: object
                            additionalProperties: false
                            properties:
                              failed_at:
                                anyOf:
                                  - anyOf:
                                      - type: string
                                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                        format: date-time
                                      - type: string
                                        format: date-time
                                  - type: "null"
                              reason_code:
                                type: string
                                pattern: ^[a-z0-9_.:-]+$
                                minLength: 1
                                maxLength: 128
                              retryable:
                                anyOf:
                                  - type: boolean
                                  - type: "null"
                              stage:
                                type: string
                                enum:
                                  - pre_execution
                                  - execution
                                  - post_fill
                                  - ledger_posting
                                  - unknown
                          - type: "null"
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        const: conversion
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fee_transaction_ids:
                        anyOf:
                          - type: array
                            items:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      ledger_posted_target_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      leg_attempt_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      posted_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      principal_transaction_id:
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      source_gross_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      source_principal_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      target_amount:
                        anyOf:
                          - required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      target_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - target_currency
                      - external_settlement_role
                      - settlement_currency
                      - internal_settlement_account_ref
                      - settlement_checked_at
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      external_settlement_role:
                        type: string
                        enum:
                          - external_source_spend
                          - external_target_disbursement
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        const: external_settlement_conversion
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      internal_settlement_account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      settlement_checked_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      settlement_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      target_currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                  - required:
                      - id
                      - family
                      - status
                      - account_ref
                      - principal_amount
                      - fee_summary
                      - fill_rate
                      - failure_reason
                      - settled_at
                      - approval_ref
                      - subject_attribution
                      - created_at
                      - updated_at
                      - family_params
                    type: object
                    additionalProperties: false
                    properties:
                      account_ref:
                        type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      admission_hold_reason:
                        anyOf:
                          - type: string
                            enum:
                              - CLIENT_NOT_VERIFIED
                              - ENTERPRISE_NOT_VERIFIED
                              - ENTERPRISE_NOT_OPERATIONAL
                              - ENTERPRISE_RESTRICTED
                              - ACCOUNT_SUSPENDED
                              - ACCOUNT_CLOSED
                              - CLIENT_SUSPENDED
                              - CLIENT_CLOSED
                          - type: "null"
                      approval_ref:
                        anyOf:
                          - required:
                              - approval_id
                              - reason_code
                              - expires_at
                            type: object
                            additionalProperties: false
                            properties:
                              approval_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              expires_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              reason_code:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          - type: "null"
                      compliance_assessment_ref:
                        anyOf:
                          - type: string
                            pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_reason:
                        anyOf:
                          - type: string
                            minLength: 1
                          - type: "null"
                      family:
                        type: string
                        enum:
                          - deposit
                          - withdrawal
                          - internal_transfer
                          - on_ramp
                          - off_ramp
                          - loan_origination
                          - loan_repayment
                          - loan_liquidation
                          - loan_closing
                          - loan_extension
                      family_params:
                        type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      fee_summary:
                        anyOf:
                          - required:
                              - components
                              - total
                            type: object
                            additionalProperties: false
                            properties:
                              components:
                                type: array
                                items:
                                  required:
                                    - kind
                                    - amount
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    amount:
                                      required:
                                        - value
                                        - currency
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        currency:
                                          description: Currency code (ISO-4217 or on-chain ticker)
                                          type: string
                                          pattern: ^[A-Z0-9]{1,16}$
                                        value:
                                          description: DecimalString
                                          type: string
                                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                    kind:
                                      type: string
                                      enum:
                                        - platform_fee
                                        - enterprise_fee
                                        - network_fee
                                        - spread
                              total:
                                required:
                                  - value
                                  - currency
                                type: object
                                additionalProperties: false
                                properties:
                                  currency:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  value:
                                    description: DecimalString
                                    type: string
                                    pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                          - type: "null"
                      fill_rate:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      principal_amount:
                        required:
                          - value
                          - currency
                        type: object
                        additionalProperties: false
                        properties:
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          value:
                            description: DecimalString
                            type: string
                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      settled_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      status:
                        type: string
                        enum:
                          - requested
                          - admissible
                          - executing
                          - pending_approval
                          - pending_admission
                          - pending_compliance
                          - executed
                          - settled
                          - ledger_visible
                          - failed
                          - cancelled
                          - partially_settled
                      subject_attribution:
                        required:
                          - authenticated_principal
                          - subject
                          - actor
                          - initiated_by
                          - approved_by
                          - identity_source
                          - federation
                          - enterprise_binding
                        type: object
                        additionalProperties: false
                        properties:
                          actor:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          approved_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          authenticated_principal:
                            required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          enterprise_binding:
                            required:
                              - topology_ref
                              - tenant_type
                            type: object
                            additionalProperties: false
                            properties:
                              tenant_type:
                                type: string
                                enum:
                                  - enterprise
                                  - platform_operator
                              topology_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          federation:
                            anyOf:
                              - required:
                                  - issuer
                                  - external_subject
                                type: object
                                additionalProperties: false
                                properties:
                                  external_subject:
                                    type: string
                                    minLength: 1
                                  issuer:
                                    type: string
                                    minLength: 1
                              - type: "null"
                          identity_source:
                            type: string
                            enum:
                              - platform-managed
                              - federated
                              - system
                          initiated_by:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                          subject:
                            anyOf:
                              - required:
                                  - id
                                  - kind
                                type: object
                                additionalProperties: false
                                properties:
                                  id:
                                    type: string
                                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                    format: uuid
                                  kind:
                                    type: string
                                    enum:
                                      - user
                                      - service
                                      - system
                                  tenant_ref:
                                    anyOf:
                                      - type: string
                                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                      - type: "null"
                              - type: "null"
                      updated_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: on_ramp_sessions.get
      x-required-capability:
        - ramps.read
  /on-ramp-sessions/{session_id}/cancel:
    post:
      summary: Cancel on-ramp session
      tags:
        - Live Operations
        - On-ramp Sessions
      security:
        - BearerAuth: []
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: on_ramp
                family_params:
                  destination_payload: {}
                  destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  source_amount:
                    currency: EUR
                    value: "250.00"
                  source_rail: fiat
                  target_currency: USDC
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: EUR
                  value: "250.00"
                settled_at: null
                status: cancelled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: on_ramp
                    family_params:
                      destination_payload: {}
                      destination_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      intermediate_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      source_amount:
                        currency: EUR
                        value: "250.00"
                      source_rail: fiat
                      target_currency: USDC
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: EUR
                      value: "250.00"
                    settled_at: null
                    status: cancelled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: on_ramp_sessions.cancel
      x-required-capability:
        - ramps.manage
  /operations-activity-exports:
    get:
      description: Lists exports within the current caller operations_reports.read
        coverage, with optional status and limit filters. limit defaults to 50
        and is bounded 1..200. Results contain an items array without cursor
        pagination.
      summary: List operations activity exports
      tags:
        - Reporting
        - Operations Activity Exports
      security:
        - BearerAuth: []
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - queued
              - running
              - ready
              - failed
              - expired
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - format: csv
                    byte_size: 32768
                    download_path: /operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                    expires_at_utc: 2026-05-02T10:00:00Z
                    failure_reason: null
                    filter_criteria:
                      date_from_utc: 2026-04-01T00:00:00Z
                      date_to_utc: 2026-04-30T23:59:59Z
                    finished_at_utc: 2026-05-01T10:00:00Z
                    generated_at_utc: 2026-05-01T10:00:00Z
                    generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requested_scope:
                      kind: enterprise
                      ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    row_count: 150
                    status: ready
                    storage_location: null
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - status
                        - format
                        - requested_scope
                        - filter_criteria
                        - generated_by
                        - generated_at_utc
                        - finished_at_utc
                        - expires_at_utc
                        - row_count
                        - byte_size
                        - storage_location
                        - download_path
                        - failure_reason
                      type: object
                      additionalProperties: false
                      properties:
                        format:
                          type: string
                          enum:
                            - csv
                            - json
                        byte_size:
                          anyOf:
                            - type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            - type: "null"
                        download_path:
                          anyOf:
                            - type: string
                            - type: "null"
                        expires_at_utc:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        failure_reason:
                          anyOf:
                            - type: string
                            - type: "null"
                        filter_criteria:
                          required:
                            - date_from_utc
                            - date_to_utc
                          type: object
                          additionalProperties: false
                          properties:
                            assets:
                              type: array
                              items:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                            client_account_refs:
                              type: array
                              items:
                                type: string
                                pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            client_refs:
                              type: array
                              items:
                                type: string
                                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            date_from_utc:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            date_to_utc:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            failure_reason_codes:
                              type: array
                              items:
                                type: string
                                minLength: 1
                            operation_families:
                              type: array
                              items:
                                type: string
                                enum:
                                  - deposit
                                  - withdrawal
                                  - conversion
                                  - external_settlement_conversion
                                  - internal_transfer
                                  - on_ramp
                                  - off_ramp
                                  - loan_origination
                                  - loan_repayment
                                  - loan_liquidation
                                  - loan_closing
                                  - loan_extension
                            statuses:
                              type: array
                              items:
                                type: string
                                enum:
                                  - created
                                  - pending_approval
                                  - in_progress
                                  - completed
                                  - failed
                                  - cancelled
                                  - reversed
                                  - corrected
                        finished_at_utc:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        generated_at_utc:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        generated_by:
                          type: string
                          pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        requested_scope:
                          oneOf:
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: enterprise
                                ref:
                                  type: string
                                  pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: master_account
                                ref:
                                  type: string
                                  pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: client
                                ref:
                                  type: string
                                  pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: client_account
                                ref:
                                  type: string
                                  pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: platform_operator
                                ref:
                                  type: string
                                  pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        row_count:
                          anyOf:
                            - type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            - type: "null"
                        status:
                          type: string
                          enum:
                            - queued
                            - running
                            - ready
                            - failed
                            - expired
                        storage_location:
                          anyOf:
                            - type: string
                            - type: "null"
                examples:
                  - items:
                      - format: csv
                        byte_size: 32768
                        download_path: /operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                        expires_at_utc: 2026-05-02T10:00:00Z
                        failure_reason: null
                        filter_criteria:
                          date_from_utc: 2026-04-01T00:00:00Z
                          date_to_utc: 2026-04-30T23:59:59Z
                        finished_at_utc: 2026-05-01T10:00:00Z
                        generated_at_utc: 2026-05-01T10:00:00Z
                        generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        requested_scope:
                          kind: enterprise
                          ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        row_count: 150
                        status: ready
                        storage_location: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: operations_activity_exports.list
      x-required-capability:
        - operations_reports.read
    post:
      description: Creates an operations activity export with format csv or json; json
        produces newline-delimited JSON. The time range must be strictly
        increasing. Requested scope requires operations_reports.create_export
        coverage; client_refs and client_account_refs filters also require
        operations_reports.read coverage. Inspect status and download_path for
        readiness. storage_location is always null; download_path is a relative
        gateway route.
      summary: Create operations activity export
      tags:
        - Reporting
        - Operations Activity Exports
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              format: csv
              filter_criteria:
                date_from_utc: 2026-04-01T00:00:00Z
                date_to_utc: 2026-04-30T23:59:59Z
              requested_scope:
                kind: enterprise
                ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - format
                - requested_scope
                - filter_criteria
              type: object
              additionalProperties: false
              properties:
                format:
                  type: string
                  enum:
                    - csv
                    - json
                filter_criteria:
                  required:
                    - date_from_utc
                    - date_to_utc
                  type: object
                  additionalProperties: false
                  properties:
                    assets:
                      type: array
                      items:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                    client_account_refs:
                      type: array
                      items:
                        type: string
                        pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    client_refs:
                      type: array
                      items:
                        type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    date_from_utc:
                      anyOf:
                        - type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        - type: string
                          format: date-time
                    date_to_utc:
                      anyOf:
                        - type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        - type: string
                          format: date-time
                    failure_reason_codes:
                      type: array
                      items:
                        type: string
                        minLength: 1
                    operation_families:
                      type: array
                      items:
                        type: string
                        enum:
                          - deposit
                          - withdrawal
                          - conversion
                          - external_settlement_conversion
                          - internal_transfer
                          - on_ramp
                          - off_ramp
                          - loan_origination
                          - loan_repayment
                          - loan_liquidation
                          - loan_closing
                          - loan_extension
                    statuses:
                      type: array
                      items:
                        type: string
                        enum:
                          - created
                          - pending_approval
                          - in_progress
                          - completed
                          - failed
                          - cancelled
                          - reversed
                          - corrected
                requested_scope:
                  oneOf:
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: enterprise
                        ref:
                          type: string
                          pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: master_account
                        ref:
                          type: string
                          pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: client
                        ref:
                          type: string
                          pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: client_account
                        ref:
                          type: string
                          pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: platform_operator
                        ref:
                          type: string
                          pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - format: csv
                  filter_criteria:
                    date_from_utc: 2026-04-01T00:00:00Z
                    date_to_utc: 2026-04-30T23:59:59Z
                  requested_scope:
                    kind: enterprise
                    ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                format: csv
                byte_size: 32768
                download_path: /operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                expires_at_utc: 2026-05-02T10:00:00Z
                failure_reason: null
                filter_criteria:
                  date_from_utc: 2026-04-01T00:00:00Z
                  date_to_utc: 2026-04-30T23:59:59Z
                finished_at_utc: 2026-05-01T10:00:00Z
                generated_at_utc: 2026-05-01T10:00:00Z
                generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requested_scope:
                  kind: enterprise
                  ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                row_count: 150
                status: ready
                storage_location: null
              schema:
                required:
                  - id
                  - status
                  - format
                  - requested_scope
                  - filter_criteria
                  - generated_by
                  - generated_at_utc
                  - finished_at_utc
                  - expires_at_utc
                  - row_count
                  - byte_size
                  - storage_location
                  - download_path
                  - failure_reason
                type: object
                additionalProperties: false
                properties:
                  format:
                    type: string
                    enum:
                      - csv
                      - json
                  byte_size:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  download_path:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  filter_criteria:
                    required:
                      - date_from_utc
                      - date_to_utc
                    type: object
                    additionalProperties: false
                    properties:
                      assets:
                        type: array
                        items:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                      client_account_refs:
                        type: array
                        items:
                          type: string
                          pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      client_refs:
                        type: array
                        items:
                          type: string
                          pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      date_from_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      date_to_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_reason_codes:
                        type: array
                        items:
                          type: string
                          minLength: 1
                      operation_families:
                        type: array
                        items:
                          type: string
                          enum:
                            - deposit
                            - withdrawal
                            - conversion
                            - external_settlement_conversion
                            - internal_transfer
                            - on_ramp
                            - off_ramp
                            - loan_origination
                            - loan_repayment
                            - loan_liquidation
                            - loan_closing
                            - loan_extension
                      statuses:
                        type: array
                        items:
                          type: string
                          enum:
                            - created
                            - pending_approval
                            - in_progress
                            - completed
                            - failed
                            - cancelled
                            - reversed
                            - corrected
                  finished_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  generated_at_utc:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  generated_by:
                    type: string
                    pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requested_scope:
                    oneOf:
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: enterprise
                          ref:
                            type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: master_account
                          ref:
                            type: string
                            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client
                          ref:
                            type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client_account
                          ref:
                            type: string
                            pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: platform_operator
                          ref:
                            type: string
                            pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  row_count:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - ready
                      - failed
                      - expired
                  storage_location:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - format: csv
                    byte_size: 32768
                    download_path: /operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                    expires_at_utc: 2026-05-02T10:00:00Z
                    failure_reason: null
                    filter_criteria:
                      date_from_utc: 2026-04-01T00:00:00Z
                      date_to_utc: 2026-04-30T23:59:59Z
                    finished_at_utc: 2026-05-01T10:00:00Z
                    generated_at_utc: 2026-05-01T10:00:00Z
                    generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requested_scope:
                      kind: enterprise
                      ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    row_count: 150
                    status: ready
                    storage_location: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: operations_activity_exports.create
      x-required-capability:
        - operations_reports.create_export
  /operations-activity-exports/{export_id}:
    get:
      description: Reads an export covered by operations_reports.read for its stored
        scope. Missing or hidden exports return 404. download_path is null until
        ready and after expiry.
      summary: Get operations activity export
      tags:
        - Reporting
        - Operations Activity Exports
      security:
        - BearerAuth: []
      parameters:
        - name: export_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                format: csv
                byte_size: 32768
                download_path: /operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                expires_at_utc: 2026-05-02T10:00:00Z
                failure_reason: null
                filter_criteria:
                  date_from_utc: 2026-04-01T00:00:00Z
                  date_to_utc: 2026-04-30T23:59:59Z
                finished_at_utc: 2026-05-01T10:00:00Z
                generated_at_utc: 2026-05-01T10:00:00Z
                generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requested_scope:
                  kind: enterprise
                  ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                row_count: 150
                status: ready
                storage_location: null
              schema:
                required:
                  - id
                  - status
                  - format
                  - requested_scope
                  - filter_criteria
                  - generated_by
                  - generated_at_utc
                  - finished_at_utc
                  - expires_at_utc
                  - row_count
                  - byte_size
                  - storage_location
                  - download_path
                  - failure_reason
                type: object
                additionalProperties: false
                properties:
                  format:
                    type: string
                    enum:
                      - csv
                      - json
                  byte_size:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  download_path:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  filter_criteria:
                    required:
                      - date_from_utc
                      - date_to_utc
                    type: object
                    additionalProperties: false
                    properties:
                      assets:
                        type: array
                        items:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                      client_account_refs:
                        type: array
                        items:
                          type: string
                          pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      client_refs:
                        type: array
                        items:
                          type: string
                          pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      date_from_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      date_to_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      failure_reason_codes:
                        type: array
                        items:
                          type: string
                          minLength: 1
                      operation_families:
                        type: array
                        items:
                          type: string
                          enum:
                            - deposit
                            - withdrawal
                            - conversion
                            - external_settlement_conversion
                            - internal_transfer
                            - on_ramp
                            - off_ramp
                            - loan_origination
                            - loan_repayment
                            - loan_liquidation
                            - loan_closing
                            - loan_extension
                      statuses:
                        type: array
                        items:
                          type: string
                          enum:
                            - created
                            - pending_approval
                            - in_progress
                            - completed
                            - failed
                            - cancelled
                            - reversed
                            - corrected
                  finished_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  generated_at_utc:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  generated_by:
                    type: string
                    pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requested_scope:
                    oneOf:
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: enterprise
                          ref:
                            type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: master_account
                          ref:
                            type: string
                            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client
                          ref:
                            type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client_account
                          ref:
                            type: string
                            pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: platform_operator
                          ref:
                            type: string
                            pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  row_count:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - ready
                      - failed
                      - expired
                  storage_location:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - format: csv
                    byte_size: 32768
                    download_path: /operations-activity-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                    expires_at_utc: 2026-05-02T10:00:00Z
                    failure_reason: null
                    filter_criteria:
                      date_from_utc: 2026-04-01T00:00:00Z
                      date_to_utc: 2026-04-30T23:59:59Z
                    finished_at_utc: 2026-05-01T10:00:00Z
                    generated_at_utc: 2026-05-01T10:00:00Z
                    generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requested_scope:
                      kind: enterprise
                      ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    row_count: 150
                    status: ready
                    storage_location: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: operations_activity_exports.get
      x-required-capability:
        - operations_reports.read
  /operations-activity-exports/{export_id}/download:
    get:
      description: "Streams the ready export through edge. csv yields text/csv and
        json yields application/x-ndjson: one JSON object per line, with UTF-8
        encoding. Content-Type, Content-Disposition and optional Content-Length
        are forwarded from the download service. Unavailable, expired or hidden
        exports return 404; an unsuccessful upstream response other than 404
        returns 502."
      summary: Download operations activity export file
      tags:
        - Reporting
        - Operations Activity Exports
      security:
        - BearerAuth: []
      parameters:
        - name: export_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/x-ndjson:
              schema:
                description: UTF-8 newline-delimited JSON, one OperationsActivityRow object per
                  line.
                type: string
            text/csv:
              schema:
                description: UTF-8 CSV file with a header row.
                type: string
          headers:
            Content-Disposition:
              schema:
                type: string
            Content-Length:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: operations_activity_exports.download
      x-required-capability:
        - operations_reports.read
  /payment-methods:
    get:
      description: Returns the global fiat deposit payment-method catalog. The `rail`
        filter uses a fiat rail code and `asset` uses a currency code;
        unsupported combinations return an empty page. This reference listing
        does not check account setup readiness. `account_ref` is rejected here;
        use `/available-payment-methods` for account-scoped discovery. Crypto
        networks are listed separately through `/crypto-networks`.
      summary: List payment methods
      tags:
        - Distribution
        - Payment Methods
      security:
        - BearerAuth: []
      parameters:
        - name: rail
          in: query
          required: false
          schema:
            type: string
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    code: sepa_credit_transfer
                    currencies:
                      - EUR
                    display_name: SEPA
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail: sepa_credit_transfer
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - code
                        - display_name
                        - rail
                        - currencies
                        - active
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        code:
                          type: string
                          pattern: ^[a-z0-9_]+$
                        currencies:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          minItems: 1
                        display_name:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        code: sepa_credit_transfer
                        currencies:
                          - EUR
                        display_name: SEPA
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail: sepa_credit_transfer
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: payment_methods.list
    post:
      description: This mutation is unavailable. The fiat payment method catalog is
        derived from asset/rail support and cannot be changed through this
        endpoint. Every valid request returns `503 rail_not_available`; no
        successful creation, update or deletion occurs. Use `GET
        /payment-methods` to read the catalog.
      summary: Create payment method
      tags:
        - Setup
        - Payment Methods
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              active: true
              code: sepa_credit_transfer
              currencies:
                - EUR
              display_name: SEPA
              rail: sepa_credit_transfer
            schema:
              required:
                - code
                - display_name
                - rail
                - currencies
              type: object
              additionalProperties: false
              properties:
                active:
                  type: boolean
                  default: true
                code:
                  type: string
                  pattern: ^[a-z0-9_]+$
                currencies:
                  type: array
                  items:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  minItems: 1
                display_name:
                  type: string
                  minLength: 1
                rail:
                  type: string
                  minLength: 1
              examples:
                - active: true
                  code: sepa_credit_transfer
                  currencies:
                    - EUR
                  display_name: SEPA
                  rail: sepa_credit_transfer
      responses:
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      deprecated: true
      operationId: payment_methods.create
      x-required-capability:
        - payment_methods.manage
  /payment-methods/{payment_method_id}:
    parameters:
      - name: payment_method_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      description: This mutation is unavailable. The fiat payment method catalog is
        derived from asset/rail support and cannot be changed through this
        endpoint. Every valid request returns `503 rail_not_available`; no
        successful creation, update or deletion occurs. Use `GET
        /payment-methods` to read the catalog.
      summary: Delete payment method
      tags:
        - Setup
        - Payment Methods
      security:
        - BearerAuth: []
      parameters:
        - name: payment_method_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      deprecated: true
      operationId: payment_methods.delete
      x-required-capability:
        - payment_methods.manage
    patch:
      description: This mutation is unavailable. The fiat payment method catalog is
        derived from asset/rail support and cannot be changed through this
        endpoint. Every valid request returns `503 rail_not_available`; no
        successful creation, update or deletion occurs. Use `GET
        /payment-methods` to read the catalog.
      summary: Update payment method
      tags:
        - Setup
        - Payment Methods
      security:
        - BearerAuth: []
      parameters:
        - name: payment_method_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            example:
              active: false
              display_name: SEPA Updated
            schema:
              type: object
              additionalProperties: false
              properties:
                active:
                  type: boolean
                currencies:
                  type: array
                  items:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  minItems: 1
                display_name:
                  type: string
                  minLength: 1
                rail:
                  type: string
                  minLength: 1
              examples:
                - active: false
                  display_name: SEPA Updated
      responses:
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      deprecated: true
      operationId: payment_methods.update
      x-required-capability:
        - payment_methods.manage
  /payout-methods:
    get:
      description: Returns the global fiat withdrawal payout-method catalog. The
        `rail` filter uses a fiat rail code and `asset` uses a currency code;
        unsupported combinations return an empty page. This reference listing
        does not establish scope eligibility or execution readiness. `scope_ref`
        is rejected here; use `/eligible-payout-methods` for an enterprise or
        client scope. Crypto networks are listed separately through
        `/crypto-networks`.
      summary: List payout methods
      tags:
        - Distribution
        - Payout Methods
      security:
        - BearerAuth: []
      parameters:
        - name: rail
          in: query
          required: false
          schema:
            type: string
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - active: true
                    code: sepa_credit_transfer
                    currencies:
                      - EUR
                    display_name: SEPA
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    rail: sepa_credit_transfer
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - code
                        - display_name
                        - rail
                        - currencies
                        - active
                      type: object
                      additionalProperties: false
                      properties:
                        active:
                          type: boolean
                        code:
                          type: string
                          pattern: ^[a-z0-9_]+$
                        currencies:
                          type: array
                          items:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          minItems: 1
                        display_name:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - active: true
                        code: sepa_credit_transfer
                        currencies:
                          - EUR
                        display_name: SEPA
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        rail: sepa_credit_transfer
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: payout_methods.list
    post:
      description: This mutation is unavailable. The fiat payout method catalog is
        derived from asset/rail support and cannot be changed through this
        endpoint. Every valid request returns `503 rail_not_available`; no
        successful creation, update or deletion occurs. Use `GET
        /payout-methods` to read the catalog.
      summary: Create payout method
      tags:
        - Setup
        - Payout Methods
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              active: true
              code: sepa_credit_transfer
              currencies:
                - EUR
              display_name: SEPA
              rail: sepa_credit_transfer
            schema:
              required:
                - code
                - display_name
                - rail
                - currencies
              type: object
              additionalProperties: false
              properties:
                active:
                  type: boolean
                  default: true
                code:
                  type: string
                  pattern: ^[a-z0-9_]+$
                currencies:
                  type: array
                  items:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  minItems: 1
                display_name:
                  type: string
                  minLength: 1
                rail:
                  type: string
                  minLength: 1
              examples:
                - active: true
                  code: sepa_credit_transfer
                  currencies:
                    - EUR
                  display_name: SEPA
                  rail: sepa_credit_transfer
      responses:
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      deprecated: true
      operationId: payout_methods.create
      x-required-capability:
        - payout_methods.manage
  /payout-methods/{payout_method_id}:
    parameters:
      - name: payout_method_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      description: This mutation is unavailable. The fiat payout method catalog is
        derived from asset/rail support and cannot be changed through this
        endpoint. Every valid request returns `503 rail_not_available`; no
        successful creation, update or deletion occurs. Use `GET
        /payout-methods` to read the catalog.
      summary: Delete payout method
      tags:
        - Setup
        - Payout Methods
      security:
        - BearerAuth: []
      parameters:
        - name: payout_method_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      deprecated: true
      operationId: payout_methods.delete
      x-required-capability:
        - payout_methods.manage
    patch:
      description: This mutation is unavailable. The fiat payout method catalog is
        derived from asset/rail support and cannot be changed through this
        endpoint. Every valid request returns `503 rail_not_available`; no
        successful creation, update or deletion occurs. Use `GET
        /payout-methods` to read the catalog.
      summary: Update payout method
      tags:
        - Setup
        - Payout Methods
      security:
        - BearerAuth: []
      parameters:
        - name: payout_method_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            example:
              active: false
              display_name: SEPA Updated
            schema:
              type: object
              additionalProperties: false
              properties:
                active:
                  type: boolean
                currencies:
                  type: array
                  items:
                    description: Currency code (ISO-4217 or on-chain ticker)
                    type: string
                    pattern: ^[A-Z0-9]{1,16}$
                  minItems: 1
                display_name:
                  type: string
                  minLength: 1
                rail:
                  type: string
                  minLength: 1
              examples:
                - active: false
                  display_name: SEPA Updated
      responses:
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      deprecated: true
      operationId: payout_methods.update
      x-required-capability:
        - payout_methods.manage
  /policy-rules:
    get:
      description: Lists visible policy rules. Filter by governed scope, operation
        type or status; repeat status_filter to select several lifecycle states.
        Draft rules are authoring resources; only active rules participate in
        policy evaluation.
      summary: List policy rules
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              - type: string
                pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: operation_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - withdrawal
              - conversion
              - external_settlement_conversion
              - internal_transfer
              - on_ramp
              - off_ramp
              - loan_origination
              - loan_repayment
              - loan_liquidation
              - loan_closing
              - loan_extension
        - name: status_filter
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - draft
                  - active
                  - retired
              - type: array
                items:
                  type: string
                  enum:
                    - draft
                    - active
                    - retired
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - name: Large crypto withdrawal approval
                    description: Require compliance review for large crypto withdrawals
                    activated_at: 2026-05-01T10:00:00Z
                    conditions:
                      - amount_basis: usd_equivalent
                        kind: amount_threshold
                        operator: gte
                        threshold:
                          currency: USD
                          value: "10000.00"
                      - asset_class: crypto
                        asset_role: principal
                        kind: asset_class
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                      initiator_cannot_approve: true
                      kind: require_approval
                      reason: large_crypto_withdrawal
                      threshold: 2
                    etag: policy-rule-v2-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_type: withdrawal
                    resource: policy_rule
                    retired_at: null
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    version: 1
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - name
                        - description
                        - scope_ref
                        - operation_type
                        - conditions
                        - decision
                        - status
                        - version
                        - created_at
                        - updated_at
                        - activated_at
                        - retired_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          minLength: 1
                        description:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        activated_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        conditions:
                          type: array
                          items:
                            oneOf:
                              - required:
                                  - kind
                                  - amount_basis
                                  - operator
                                  - threshold
                                type: object
                                additionalProperties: false
                                properties:
                                  amount_basis:
                                    type: string
                                    enum:
                                      - native_amount
                                      - usd_equivalent
                                  kind:
                                    type: string
                                    const: amount_threshold
                                  operator:
                                    type: string
                                    enum:
                                      - gt
                                      - gte
                                      - lt
                                      - lte
                                  threshold:
                                    required:
                                      - value
                                      - currency
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      currency:
                                        description: Currency code (ISO-4217 or on-chain ticker)
                                        type: string
                                        pattern: ^[A-Z0-9]{1,16}$
                                      value:
                                        description: DecimalString
                                        type: string
                                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                              - required:
                                  - kind
                                  - asset_role
                                  - asset_class
                                type: object
                                additionalProperties: false
                                properties:
                                  asset_class:
                                    type: string
                                    enum:
                                      - fiat
                                      - crypto
                                  asset_role:
                                    type: string
                                    enum:
                                      - principal
                                      - source
                                      - target
                                  kind:
                                    type: string
                                    const: asset_class
                              - required:
                                  - kind
                                  - asset_role
                                  - asset_code
                                type: object
                                additionalProperties: false
                                properties:
                                  asset_code:
                                    description: Currency code (ISO-4217 or on-chain ticker)
                                    type: string
                                    pattern: ^[A-Z0-9]{1,16}$
                                  asset_role:
                                    type: string
                                    enum:
                                      - principal
                                      - source
                                      - target
                                  kind:
                                    type: string
                                    const: asset
                              - required:
                                  - kind
                                  - direction
                                type: object
                                additionalProperties: false
                                properties:
                                  direction:
                                    type: string
                                    enum:
                                      - master_to_client
                                      - client_to_master
                                      - client_to_client
                                  kind:
                                    type: string
                                    const: direction
                              - required:
                                  - kind
                                  - initiator_ref
                                type: object
                                additionalProperties: false
                                properties:
                                  initiator_ref:
                                    type: string
                                    pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  kind:
                                    type: string
                                    const: initiator
                              - required:
                                  - kind
                                  - source_asset_class
                                  - target_asset_class
                                type: object
                                additionalProperties: false
                                properties:
                                  kind:
                                    type: string
                                    const: conversion_asset_class_pair
                                  source_asset_class:
                                    type: string
                                    enum:
                                      - fiat
                                      - crypto
                                  target_asset_class:
                                    type: string
                                    enum:
                                      - fiat
                                      - crypto
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        decision:
                          oneOf:
                            - required:
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: allow
                                reason:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                    - type: "null"
                            - required:
                                - kind
                                - reason
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: deny
                                reason:
                                  type: string
                                  minLength: 1
                            - required:
                                - kind
                                - reason
                                - threshold
                                - initiator_cannot_approve
                              type: object
                              additionalProperties: false
                              properties:
                                approver_role_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                                initiator_cannot_approve:
                                  type: boolean
                                kind:
                                  type: string
                                  const: require_approval
                                reason:
                                  type: string
                                  minLength: 1
                                threshold:
                                  type: integer
                                  maximum: 9007199254740991
                                  exclusiveMinimum: 0
                        etag:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        operation_type:
                          type: string
                          enum:
                            - withdrawal
                            - conversion
                            - external_settlement_conversion
                            - internal_transfer
                            - on_ramp
                            - off_ramp
                            - loan_origination
                            - loan_repayment
                            - loan_liquidation
                            - loan_closing
                            - loan_extension
                        resource:
                          type: string
                          const: policy_rule
                        retired_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        scope_ref:
                          anyOf:
                            - type: string
                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: string
                              pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - draft
                            - active
                            - retired
                        updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        version:
                          type: integer
                          maximum: 9007199254740991
                          exclusiveMinimum: 0
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - name: Large crypto withdrawal approval
                        description: Require compliance review for large crypto withdrawals
                        activated_at: 2026-05-01T10:00:00Z
                        conditions:
                          - amount_basis: usd_equivalent
                            kind: amount_threshold
                            operator: gte
                            threshold:
                              currency: USD
                              value: "10000.00"
                          - asset_class: crypto
                            asset_role: principal
                            kind: asset_class
                        created_at: 2026-05-01T10:00:00Z
                        decision:
                          approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                          initiator_cannot_approve: true
                          kind: require_approval
                          reason: large_crypto_withdrawal
                          threshold: 2
                        etag: policy-rule-v2-0001
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        operation_type: withdrawal
                        resource: policy_rule
                        retired_at: null
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                        version: 1
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: policy_rules.list
      x-required-capability:
        - policies.read
    post:
      description: "Creates a draft rule under the governed scope. Creating a rule
        does not enforce it: activate the draft separately after authoring.
        Supply Idempotency-Key for replay-safe creation; it takes precedence
        over body idempotency_key. When neither is supplied, edge generates a
        key and a repeated request creates a new rule. A replay with the same
        Idempotency-Key header returns the original 201 response and original
        etag. A body-only idempotency_key replay returns the existing rule in
        its current lifecycle state. Re-read the rule before a later lifecycle
        action."
      summary: Create policy rule
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Large crypto withdrawal approval
              description: Require compliance review for large crypto withdrawals
              conditions:
                - amount_basis: usd_equivalent
                  kind: amount_threshold
                  operator: gte
                  threshold:
                    currency: USD
                    value: "10000.00"
                - asset_class: crypto
                  asset_role: principal
                  kind: asset_class
              decision:
                approver_role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                initiator_cannot_approve: true
                kind: require_approval
                reason: large_crypto_withdrawal
                threshold: 2
              operation_type: withdrawal
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - name
                - scope_ref
                - operation_type
                - conditions
                - decision
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  minLength: 1
                description:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: "null"
                conditions:
                  type: array
                  items:
                    oneOf:
                      - required:
                          - kind
                          - amount_basis
                          - operator
                          - threshold
                        type: object
                        additionalProperties: false
                        properties:
                          amount_basis:
                            type: string
                            enum:
                              - native_amount
                              - usd_equivalent
                          kind:
                            type: string
                            const: amount_threshold
                          operator:
                            type: string
                            enum:
                              - gt
                              - gte
                              - lt
                              - lte
                          threshold:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - required:
                          - kind
                          - asset_role
                          - asset_class
                        type: object
                        additionalProperties: false
                        properties:
                          asset_class:
                            type: string
                            enum:
                              - fiat
                              - crypto
                          asset_role:
                            type: string
                            enum:
                              - principal
                              - source
                              - target
                          kind:
                            type: string
                            const: asset_class
                      - required:
                          - kind
                          - asset_role
                          - asset_code
                        type: object
                        additionalProperties: false
                        properties:
                          asset_code:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          asset_role:
                            type: string
                            enum:
                              - principal
                              - source
                              - target
                          kind:
                            type: string
                            const: asset
                      - required:
                          - kind
                          - direction
                        type: object
                        additionalProperties: false
                        properties:
                          direction:
                            type: string
                            enum:
                              - master_to_client
                              - client_to_master
                              - client_to_client
                          kind:
                            type: string
                            const: direction
                      - required:
                          - kind
                          - initiator_ref
                        type: object
                        additionalProperties: false
                        properties:
                          initiator_ref:
                            type: string
                            pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          kind:
                            type: string
                            const: initiator
                      - required:
                          - kind
                          - source_asset_class
                          - target_asset_class
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: conversion_asset_class_pair
                          source_asset_class:
                            type: string
                            enum:
                              - fiat
                              - crypto
                          target_asset_class:
                            type: string
                            enum:
                              - fiat
                              - crypto
                decision:
                  oneOf:
                    - required:
                        - kind
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: allow
                        reason:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                    - required:
                        - kind
                        - reason
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: deny
                        reason:
                          type: string
                          minLength: 1
                    - required:
                        - kind
                        - reason
                        - threshold
                        - initiator_cannot_approve
                      type: object
                      additionalProperties: false
                      properties:
                        approver_role_ref:
                          anyOf:
                            - type: string
                              pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        initiator_cannot_approve:
                          type: boolean
                        kind:
                          type: string
                          const: require_approval
                        reason:
                          type: string
                          minLength: 1
                        threshold:
                          type: integer
                          maximum: 9007199254740991
                          exclusiveMinimum: 0
                idempotency_key:
                  type: string
                  minLength: 1
                  maxLength: 128
                operation_type:
                  type: string
                  enum:
                    - withdrawal
                    - conversion
                    - external_settlement_conversion
                    - internal_transfer
                    - on_ramp
                    - off_ramp
                    - loan_origination
                    - loan_repayment
                    - loan_liquidation
                    - loan_closing
                    - loan_extension
                scope_ref:
                  anyOf:
                    - type: string
                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - name: Large crypto withdrawal approval
                  description: Require compliance review for large crypto withdrawals
                  conditions:
                    - amount_basis: usd_equivalent
                      kind: amount_threshold
                      operator: gte
                      threshold:
                        currency: USD
                        value: "10000.00"
                    - asset_class: crypto
                      asset_role: principal
                      kind: asset_class
                  decision:
                    approver_role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    initiator_cannot_approve: true
                    kind: require_approval
                    reason: large_crypto_withdrawal
                    threshold: 2
                  operation_type: withdrawal
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                name: Large crypto withdrawal approval
                description: Require compliance review for large crypto withdrawals
                activated_at: null
                conditions:
                  - amount_basis: usd_equivalent
                    kind: amount_threshold
                    operator: gte
                    threshold:
                      currency: USD
                      value: "10000.00"
                  - asset_class: crypto
                    asset_role: principal
                    kind: asset_class
                created_at: 2026-05-01T10:00:00Z
                decision:
                  approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                  initiator_cannot_approve: true
                  kind: require_approval
                  reason: large_crypto_withdrawal
                  threshold: 2
                etag: policy-rule-v2-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_type: withdrawal
                resource: policy_rule
                retired_at: null
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: draft
                updated_at: 2026-05-01T10:00:00Z
                version: 1
              schema:
                required:
                  - id
                  - resource
                  - name
                  - description
                  - scope_ref
                  - operation_type
                  - conditions
                  - decision
                  - status
                  - version
                  - created_at
                  - updated_at
                  - activated_at
                  - retired_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  activated_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  conditions:
                    type: array
                    items:
                      oneOf:
                        - required:
                            - kind
                            - amount_basis
                            - operator
                            - threshold
                          type: object
                          additionalProperties: false
                          properties:
                            amount_basis:
                              type: string
                              enum:
                                - native_amount
                                - usd_equivalent
                            kind:
                              type: string
                              const: amount_threshold
                            operator:
                              type: string
                              enum:
                                - gt
                                - gte
                                - lt
                                - lte
                            threshold:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        - required:
                            - kind
                            - asset_role
                            - asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset_class
                        - required:
                            - kind
                            - asset_role
                            - asset_code
                          type: object
                          additionalProperties: false
                          properties:
                            asset_code:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset
                        - required:
                            - kind
                            - direction
                          type: object
                          additionalProperties: false
                          properties:
                            direction:
                              type: string
                              enum:
                                - master_to_client
                                - client_to_master
                                - client_to_client
                            kind:
                              type: string
                              const: direction
                        - required:
                            - kind
                            - initiator_ref
                          type: object
                          additionalProperties: false
                          properties:
                            initiator_ref:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            kind:
                              type: string
                              const: initiator
                        - required:
                            - kind
                            - source_asset_class
                            - target_asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            kind:
                              type: string
                              const: conversion_asset_class_pair
                            source_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            target_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  decision:
                    oneOf:
                      - required:
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: allow
                          reason:
                            anyOf:
                              - type: string
                                minLength: 1
                              - type: "null"
                      - required:
                          - kind
                          - reason
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: deny
                          reason:
                            type: string
                            minLength: 1
                      - required:
                          - kind
                          - reason
                          - threshold
                          - initiator_cannot_approve
                        type: object
                        additionalProperties: false
                        properties:
                          approver_role_ref:
                            anyOf:
                              - type: string
                                pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                          initiator_cannot_approve:
                            type: boolean
                          kind:
                            type: string
                            const: require_approval
                          reason:
                            type: string
                            minLength: 1
                          threshold:
                            type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  operation_type:
                    type: string
                    enum:
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  resource:
                    type: string
                    const: policy_rule
                  retired_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - draft
                      - active
                      - retired
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  version:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                examples:
                  - name: Large crypto withdrawal approval
                    description: Require compliance review for large crypto withdrawals
                    activated_at: null
                    conditions:
                      - amount_basis: usd_equivalent
                        kind: amount_threshold
                        operator: gte
                        threshold:
                          currency: USD
                          value: "10000.00"
                      - asset_class: crypto
                        asset_role: principal
                        kind: asset_class
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                      initiator_cannot_approve: true
                      kind: require_approval
                      reason: large_crypto_withdrawal
                      threshold: 2
                    etag: policy-rule-v2-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_type: withdrawal
                    resource: policy_rule
                    retired_at: null
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: draft
                    updated_at: 2026-05-01T10:00:00Z
                    version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: policy_rules.create
      x-required-capability:
        - policies.create
  /policy-rules/{rule_id}:
    parameters:
      - name: rule_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: Reads a visible policy rule. Use its ETag response header or etag
        body field as If-Match when updating, activating or retiring the rule.
      summary: Get policy rule
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                name: Large crypto withdrawal approval
                description: Require compliance review for large crypto withdrawals
                activated_at: 2026-05-01T10:00:00Z
                conditions:
                  - amount_basis: usd_equivalent
                    kind: amount_threshold
                    operator: gte
                    threshold:
                      currency: USD
                      value: "10000.00"
                  - asset_class: crypto
                    asset_role: principal
                    kind: asset_class
                created_at: 2026-05-01T10:00:00Z
                decision:
                  approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                  initiator_cannot_approve: true
                  kind: require_approval
                  reason: large_crypto_withdrawal
                  threshold: 2
                etag: policy-rule-v2-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_type: withdrawal
                resource: policy_rule
                retired_at: null
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
                version: 1
              schema:
                required:
                  - id
                  - resource
                  - name
                  - description
                  - scope_ref
                  - operation_type
                  - conditions
                  - decision
                  - status
                  - version
                  - created_at
                  - updated_at
                  - activated_at
                  - retired_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  activated_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  conditions:
                    type: array
                    items:
                      oneOf:
                        - required:
                            - kind
                            - amount_basis
                            - operator
                            - threshold
                          type: object
                          additionalProperties: false
                          properties:
                            amount_basis:
                              type: string
                              enum:
                                - native_amount
                                - usd_equivalent
                            kind:
                              type: string
                              const: amount_threshold
                            operator:
                              type: string
                              enum:
                                - gt
                                - gte
                                - lt
                                - lte
                            threshold:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        - required:
                            - kind
                            - asset_role
                            - asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset_class
                        - required:
                            - kind
                            - asset_role
                            - asset_code
                          type: object
                          additionalProperties: false
                          properties:
                            asset_code:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset
                        - required:
                            - kind
                            - direction
                          type: object
                          additionalProperties: false
                          properties:
                            direction:
                              type: string
                              enum:
                                - master_to_client
                                - client_to_master
                                - client_to_client
                            kind:
                              type: string
                              const: direction
                        - required:
                            - kind
                            - initiator_ref
                          type: object
                          additionalProperties: false
                          properties:
                            initiator_ref:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            kind:
                              type: string
                              const: initiator
                        - required:
                            - kind
                            - source_asset_class
                            - target_asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            kind:
                              type: string
                              const: conversion_asset_class_pair
                            source_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            target_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  decision:
                    oneOf:
                      - required:
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: allow
                          reason:
                            anyOf:
                              - type: string
                                minLength: 1
                              - type: "null"
                      - required:
                          - kind
                          - reason
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: deny
                          reason:
                            type: string
                            minLength: 1
                      - required:
                          - kind
                          - reason
                          - threshold
                          - initiator_cannot_approve
                        type: object
                        additionalProperties: false
                        properties:
                          approver_role_ref:
                            anyOf:
                              - type: string
                                pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                          initiator_cannot_approve:
                            type: boolean
                          kind:
                            type: string
                            const: require_approval
                          reason:
                            type: string
                            minLength: 1
                          threshold:
                            type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  operation_type:
                    type: string
                    enum:
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  resource:
                    type: string
                    const: policy_rule
                  retired_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - draft
                      - active
                      - retired
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  version:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                examples:
                  - name: Large crypto withdrawal approval
                    description: Require compliance review for large crypto withdrawals
                    activated_at: 2026-05-01T10:00:00Z
                    conditions:
                      - amount_basis: usd_equivalent
                        kind: amount_threshold
                        operator: gte
                        threshold:
                          currency: USD
                          value: "10000.00"
                      - asset_class: crypto
                        asset_role: principal
                        kind: asset_class
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                      initiator_cannot_approve: true
                      kind: require_approval
                      reason: large_crypto_withdrawal
                      threshold: 2
                    etag: policy-rule-v2-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_type: withdrawal
                    resource: policy_rule
                    retired_at: null
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: policy_rules.get
      x-required-capability:
        - policies.read
    patch:
      description: Updates authoring fields on a draft rule. Active and retired rules
        cannot be edited. If-Match is required and must match the current rule
        etag; stale values are refused. Only supplied fields change, and
        description may be null.
      summary: Update policy rule
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Updated policy rule name
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  minLength: 1
                description:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: "null"
                conditions:
                  type: array
                  items:
                    oneOf:
                      - required:
                          - kind
                          - amount_basis
                          - operator
                          - threshold
                        type: object
                        additionalProperties: false
                        properties:
                          amount_basis:
                            type: string
                            enum:
                              - native_amount
                              - usd_equivalent
                          kind:
                            type: string
                            const: amount_threshold
                          operator:
                            type: string
                            enum:
                              - gt
                              - gte
                              - lt
                              - lte
                          threshold:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - required:
                          - kind
                          - asset_role
                          - asset_class
                        type: object
                        additionalProperties: false
                        properties:
                          asset_class:
                            type: string
                            enum:
                              - fiat
                              - crypto
                          asset_role:
                            type: string
                            enum:
                              - principal
                              - source
                              - target
                          kind:
                            type: string
                            const: asset_class
                      - required:
                          - kind
                          - asset_role
                          - asset_code
                        type: object
                        additionalProperties: false
                        properties:
                          asset_code:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          asset_role:
                            type: string
                            enum:
                              - principal
                              - source
                              - target
                          kind:
                            type: string
                            const: asset
                      - required:
                          - kind
                          - direction
                        type: object
                        additionalProperties: false
                        properties:
                          direction:
                            type: string
                            enum:
                              - master_to_client
                              - client_to_master
                              - client_to_client
                          kind:
                            type: string
                            const: direction
                      - required:
                          - kind
                          - initiator_ref
                        type: object
                        additionalProperties: false
                        properties:
                          initiator_ref:
                            type: string
                            pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          kind:
                            type: string
                            const: initiator
                      - required:
                          - kind
                          - source_asset_class
                          - target_asset_class
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: conversion_asset_class_pair
                          source_asset_class:
                            type: string
                            enum:
                              - fiat
                              - crypto
                          target_asset_class:
                            type: string
                            enum:
                              - fiat
                              - crypto
                decision:
                  oneOf:
                    - required:
                        - kind
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: allow
                        reason:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                    - required:
                        - kind
                        - reason
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: deny
                        reason:
                          type: string
                          minLength: 1
                    - required:
                        - kind
                        - reason
                        - threshold
                        - initiator_cannot_approve
                      type: object
                      additionalProperties: false
                      properties:
                        approver_role_ref:
                          anyOf:
                            - type: string
                              pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        initiator_cannot_approve:
                          type: boolean
                        kind:
                          type: string
                          const: require_approval
                        reason:
                          type: string
                          minLength: 1
                        threshold:
                          type: integer
                          maximum: 9007199254740991
                          exclusiveMinimum: 0
                operation_type:
                  type: string
                  enum:
                    - withdrawal
                    - conversion
                    - external_settlement_conversion
                    - internal_transfer
                    - on_ramp
                    - off_ramp
                    - loan_origination
                    - loan_repayment
                    - loan_liquidation
                    - loan_closing
                    - loan_extension
                scope_ref:
                  anyOf:
                    - type: string
                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - name: Updated policy rule name
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                name: Large crypto withdrawal approval
                description: Require compliance review for large crypto withdrawals
                activated_at: null
                conditions:
                  - amount_basis: usd_equivalent
                    kind: amount_threshold
                    operator: gte
                    threshold:
                      currency: USD
                      value: "10000.00"
                  - asset_class: crypto
                    asset_role: principal
                    kind: asset_class
                created_at: 2026-05-01T10:00:00Z
                decision:
                  approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                  initiator_cannot_approve: true
                  kind: require_approval
                  reason: large_crypto_withdrawal
                  threshold: 2
                etag: policy-rule-v2-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_type: withdrawal
                resource: policy_rule
                retired_at: null
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: draft
                updated_at: 2026-05-01T10:00:00Z
                version: 1
              schema:
                required:
                  - id
                  - resource
                  - name
                  - description
                  - scope_ref
                  - operation_type
                  - conditions
                  - decision
                  - status
                  - version
                  - created_at
                  - updated_at
                  - activated_at
                  - retired_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  activated_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  conditions:
                    type: array
                    items:
                      oneOf:
                        - required:
                            - kind
                            - amount_basis
                            - operator
                            - threshold
                          type: object
                          additionalProperties: false
                          properties:
                            amount_basis:
                              type: string
                              enum:
                                - native_amount
                                - usd_equivalent
                            kind:
                              type: string
                              const: amount_threshold
                            operator:
                              type: string
                              enum:
                                - gt
                                - gte
                                - lt
                                - lte
                            threshold:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        - required:
                            - kind
                            - asset_role
                            - asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset_class
                        - required:
                            - kind
                            - asset_role
                            - asset_code
                          type: object
                          additionalProperties: false
                          properties:
                            asset_code:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset
                        - required:
                            - kind
                            - direction
                          type: object
                          additionalProperties: false
                          properties:
                            direction:
                              type: string
                              enum:
                                - master_to_client
                                - client_to_master
                                - client_to_client
                            kind:
                              type: string
                              const: direction
                        - required:
                            - kind
                            - initiator_ref
                          type: object
                          additionalProperties: false
                          properties:
                            initiator_ref:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            kind:
                              type: string
                              const: initiator
                        - required:
                            - kind
                            - source_asset_class
                            - target_asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            kind:
                              type: string
                              const: conversion_asset_class_pair
                            source_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            target_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  decision:
                    oneOf:
                      - required:
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: allow
                          reason:
                            anyOf:
                              - type: string
                                minLength: 1
                              - type: "null"
                      - required:
                          - kind
                          - reason
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: deny
                          reason:
                            type: string
                            minLength: 1
                      - required:
                          - kind
                          - reason
                          - threshold
                          - initiator_cannot_approve
                        type: object
                        additionalProperties: false
                        properties:
                          approver_role_ref:
                            anyOf:
                              - type: string
                                pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                          initiator_cannot_approve:
                            type: boolean
                          kind:
                            type: string
                            const: require_approval
                          reason:
                            type: string
                            minLength: 1
                          threshold:
                            type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  operation_type:
                    type: string
                    enum:
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  resource:
                    type: string
                    const: policy_rule
                  retired_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - draft
                      - active
                      - retired
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  version:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                examples:
                  - name: Large crypto withdrawal approval
                    description: Require compliance review for large crypto withdrawals
                    activated_at: null
                    conditions:
                      - amount_basis: usd_equivalent
                        kind: amount_threshold
                        operator: gte
                        threshold:
                          currency: USD
                          value: "10000.00"
                      - asset_class: crypto
                        asset_role: principal
                        kind: asset_class
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                      initiator_cannot_approve: true
                      kind: require_approval
                      reason: large_crypto_withdrawal
                      threshold: 2
                    etag: policy-rule-v2-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_type: withdrawal
                    resource: policy_rule
                    retired_at: null
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: draft
                    updated_at: 2026-05-01T10:00:00Z
                    version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: policy_rules.update
      x-required-capability:
        - policies.manage
  /policy-rules/{rule_id}/activate:
    post:
      description: Validates a draft and activates it for policy evaluation. If-Match
        must match the current rule etag. A named approver role must be active,
        lie within the governed perimeter and permit approval decisions;
        omitting the role leaves eligible approvers to the governed perimeter.
        Only draft rules can be activated.
      summary: Activate policy rule
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                name: Large crypto withdrawal approval
                description: Require compliance review for large crypto withdrawals
                activated_at: 2026-05-01T10:00:00Z
                conditions:
                  - amount_basis: usd_equivalent
                    kind: amount_threshold
                    operator: gte
                    threshold:
                      currency: USD
                      value: "10000.00"
                  - asset_class: crypto
                    asset_role: principal
                    kind: asset_class
                created_at: 2026-05-01T10:00:00Z
                decision:
                  approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                  initiator_cannot_approve: true
                  kind: require_approval
                  reason: large_crypto_withdrawal
                  threshold: 2
                etag: policy-rule-v2-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_type: withdrawal
                resource: policy_rule
                retired_at: null
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
                version: 1
              schema:
                required:
                  - id
                  - resource
                  - name
                  - description
                  - scope_ref
                  - operation_type
                  - conditions
                  - decision
                  - status
                  - version
                  - created_at
                  - updated_at
                  - activated_at
                  - retired_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  activated_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  conditions:
                    type: array
                    items:
                      oneOf:
                        - required:
                            - kind
                            - amount_basis
                            - operator
                            - threshold
                          type: object
                          additionalProperties: false
                          properties:
                            amount_basis:
                              type: string
                              enum:
                                - native_amount
                                - usd_equivalent
                            kind:
                              type: string
                              const: amount_threshold
                            operator:
                              type: string
                              enum:
                                - gt
                                - gte
                                - lt
                                - lte
                            threshold:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        - required:
                            - kind
                            - asset_role
                            - asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset_class
                        - required:
                            - kind
                            - asset_role
                            - asset_code
                          type: object
                          additionalProperties: false
                          properties:
                            asset_code:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset
                        - required:
                            - kind
                            - direction
                          type: object
                          additionalProperties: false
                          properties:
                            direction:
                              type: string
                              enum:
                                - master_to_client
                                - client_to_master
                                - client_to_client
                            kind:
                              type: string
                              const: direction
                        - required:
                            - kind
                            - initiator_ref
                          type: object
                          additionalProperties: false
                          properties:
                            initiator_ref:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            kind:
                              type: string
                              const: initiator
                        - required:
                            - kind
                            - source_asset_class
                            - target_asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            kind:
                              type: string
                              const: conversion_asset_class_pair
                            source_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            target_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  decision:
                    oneOf:
                      - required:
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: allow
                          reason:
                            anyOf:
                              - type: string
                                minLength: 1
                              - type: "null"
                      - required:
                          - kind
                          - reason
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: deny
                          reason:
                            type: string
                            minLength: 1
                      - required:
                          - kind
                          - reason
                          - threshold
                          - initiator_cannot_approve
                        type: object
                        additionalProperties: false
                        properties:
                          approver_role_ref:
                            anyOf:
                              - type: string
                                pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                          initiator_cannot_approve:
                            type: boolean
                          kind:
                            type: string
                            const: require_approval
                          reason:
                            type: string
                            minLength: 1
                          threshold:
                            type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  operation_type:
                    type: string
                    enum:
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  resource:
                    type: string
                    const: policy_rule
                  retired_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - draft
                      - active
                      - retired
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  version:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                examples:
                  - name: Large crypto withdrawal approval
                    description: Require compliance review for large crypto withdrawals
                    activated_at: 2026-05-01T10:00:00Z
                    conditions:
                      - amount_basis: usd_equivalent
                        kind: amount_threshold
                        operator: gte
                        threshold:
                          currency: USD
                          value: "10000.00"
                      - asset_class: crypto
                        asset_role: principal
                        kind: asset_class
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                      initiator_cannot_approve: true
                      kind: require_approval
                      reason: large_crypto_withdrawal
                      threshold: 2
                    etag: policy-rule-v2-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_type: withdrawal
                    resource: policy_rule
                    retired_at: null
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: policy_rules.activate
      x-required-capability:
        - policies.manage
  /policy-rules/{rule_id}/retire:
    post:
      description: Retires a draft or active rule while preserving its history.
        If-Match must match the current rule etag. Retired rules no longer
        participate in evaluation and cannot be retired again. The optional body
        may supply a nullable reason.
      summary: Retire policy rule
      tags:
        - Setup
        - Policies
      security:
        - BearerAuth: []
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              reason: No longer needed
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: "null"
              examples:
                - reason: No longer needed
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                name: Large crypto withdrawal approval
                description: Require compliance review for large crypto withdrawals
                activated_at: 2026-05-01T10:00:00Z
                conditions:
                  - amount_basis: usd_equivalent
                    kind: amount_threshold
                    operator: gte
                    threshold:
                      currency: USD
                      value: "10000.00"
                  - asset_class: crypto
                    asset_role: principal
                    kind: asset_class
                created_at: 2026-05-01T10:00:00Z
                decision:
                  approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                  initiator_cannot_approve: true
                  kind: require_approval
                  reason: large_crypto_withdrawal
                  threshold: 2
                etag: policy-rule-v2-0001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                operation_type: withdrawal
                resource: policy_rule
                retired_at: 2026-05-01T10:00:00Z
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: retired
                updated_at: 2026-05-01T10:00:00Z
                version: 1
              schema:
                required:
                  - id
                  - resource
                  - name
                  - description
                  - scope_ref
                  - operation_type
                  - conditions
                  - decision
                  - status
                  - version
                  - created_at
                  - updated_at
                  - activated_at
                  - retired_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  activated_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  conditions:
                    type: array
                    items:
                      oneOf:
                        - required:
                            - kind
                            - amount_basis
                            - operator
                            - threshold
                          type: object
                          additionalProperties: false
                          properties:
                            amount_basis:
                              type: string
                              enum:
                                - native_amount
                                - usd_equivalent
                            kind:
                              type: string
                              const: amount_threshold
                            operator:
                              type: string
                              enum:
                                - gt
                                - gte
                                - lt
                                - lte
                            threshold:
                              required:
                                - value
                                - currency
                              type: object
                              additionalProperties: false
                              properties:
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                value:
                                  description: DecimalString
                                  type: string
                                  pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        - required:
                            - kind
                            - asset_role
                            - asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset_class
                        - required:
                            - kind
                            - asset_role
                            - asset_code
                          type: object
                          additionalProperties: false
                          properties:
                            asset_code:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            asset_role:
                              type: string
                              enum:
                                - principal
                                - source
                                - target
                            kind:
                              type: string
                              const: asset
                        - required:
                            - kind
                            - direction
                          type: object
                          additionalProperties: false
                          properties:
                            direction:
                              type: string
                              enum:
                                - master_to_client
                                - client_to_master
                                - client_to_client
                            kind:
                              type: string
                              const: direction
                        - required:
                            - kind
                            - initiator_ref
                          type: object
                          additionalProperties: false
                          properties:
                            initiator_ref:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            kind:
                              type: string
                              const: initiator
                        - required:
                            - kind
                            - source_asset_class
                            - target_asset_class
                          type: object
                          additionalProperties: false
                          properties:
                            kind:
                              type: string
                              const: conversion_asset_class_pair
                            source_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                            target_asset_class:
                              type: string
                              enum:
                                - fiat
                                - crypto
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  decision:
                    oneOf:
                      - required:
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: allow
                          reason:
                            anyOf:
                              - type: string
                                minLength: 1
                              - type: "null"
                      - required:
                          - kind
                          - reason
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: deny
                          reason:
                            type: string
                            minLength: 1
                      - required:
                          - kind
                          - reason
                          - threshold
                          - initiator_cannot_approve
                        type: object
                        additionalProperties: false
                        properties:
                          approver_role_ref:
                            anyOf:
                              - type: string
                                pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                          initiator_cannot_approve:
                            type: boolean
                          kind:
                            type: string
                            const: require_approval
                          reason:
                            type: string
                            minLength: 1
                          threshold:
                            type: integer
                            maximum: 9007199254740991
                            exclusiveMinimum: 0
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  operation_type:
                    type: string
                    enum:
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  resource:
                    type: string
                    const: policy_rule
                  retired_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - draft
                      - active
                      - retired
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  version:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                examples:
                  - name: Large crypto withdrawal approval
                    description: Require compliance review for large crypto withdrawals
                    activated_at: 2026-05-01T10:00:00Z
                    conditions:
                      - amount_basis: usd_equivalent
                        kind: amount_threshold
                        operator: gte
                        threshold:
                          currency: USD
                          value: "10000.00"
                      - asset_class: crypto
                        asset_role: principal
                        kind: asset_class
                    created_at: 2026-05-01T10:00:00Z
                    decision:
                      approver_role_ref: roles/44444444-4444-4444-8444-444444444444
                      initiator_cannot_approve: true
                      kind: require_approval
                      reason: large_crypto_withdrawal
                      threshold: 2
                    etag: policy-rule-v2-0001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    operation_type: withdrawal
                    resource: policy_rule
                    retired_at: 2026-05-01T10:00:00Z
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: retired
                    updated_at: 2026-05-01T10:00:00Z
                    version: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: policy_rules.retire
      x-required-capability:
        - policies.manage
  /prices/assets:
    get:
      description: "Returns the current price of each requested asset expressed in
        `quote_asset`, plus the absolute change over a trailing 24-hour window.
        `assets` is a comma-separated list (max 50). `account_ref` requires a
        bound enterprise or client operating scope; missing/platform bindings
        are refused with 403 and an account outside that scope is hidden with
        404. Asset codes are trimmed, uppercased and deduplicated; quote_asset
        is trimmed and uppercased. The price is account-scoped: the price is
        produced by the same pricing source that prices a conversion for that
        account, and the 24h change is attributed to the venue resolved for that
        account and pair. `change_24h` is `null` — never `0` — whenever the
        change cannot be established honestly (the venue publishes no rolling
        24-hour reference price, the pair routes to the internal book, or the
        venue stats call failed); a `null` must not be rendered as a flat
        market. Assets that could not be priced are listed under `unavailable`
        with a machine-readable reason instead of being silently dropped. This
        response is informational only; execution must request pricing again."
      summary: Get per-asset prices
      tags:
        - Live Operations
        - Prices
      security:
        - BearerAuth: []
      parameters:
        - name: assets
          in: query
          required: true
          schema:
            description: Comma-separated asset codes, e.g. `BTC,ETH,SOL`. Max 50.
            type: string
            minLength: 1
        - name: quote_asset
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                prices:
                  - asset: BTC
                    calculated_at: 2026-05-01T10:00:00Z
                    change_24h: "-1204.31"
                    change_source: binance:BTCUSDC
                    price: "65789.47"
                    price_source: binance:ws:via_usdc
                  - asset: ETH
                    calculated_at: 2026-05-01T10:00:00Z
                    change_24h: null
                    change_source: null
                    price: "3421.08"
                    price_source: binance:ws:via_usdc
                quote_asset: USD
                unavailable:
                  - asset: SOL
                    reason: unknown_pair
              schema:
                required:
                  - quote_asset
                  - prices
                  - unavailable
                type: object
                additionalProperties: false
                properties:
                  prices:
                    type: array
                    items:
                      required:
                        - asset
                        - price
                        - change_24h
                        - price_source
                        - change_source
                        - calculated_at
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          type: string
                          minLength: 1
                        calculated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        change_24h:
                          anyOf:
                            - description: SignedDecimalString
                              type: string
                              pattern: ^-?(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        change_source:
                          anyOf:
                            - type: string
                            - type: "null"
                        price:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        price_source:
                          anyOf:
                            - type: string
                            - type: "null"
                  quote_asset:
                    type: string
                    minLength: 1
                  unavailable:
                    type: array
                    items:
                      required:
                        - asset
                        - reason
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          type: string
                          minLength: 1
                        reason:
                          type: string
                          enum:
                            - unknown_pair
                            - pricing_unavailable
                examples:
                  - prices:
                      - asset: BTC
                        calculated_at: 2026-05-01T10:00:00Z
                        change_24h: "-1204.31"
                        change_source: binance:BTCUSDC
                        price: "65789.47"
                        price_source: binance:ws:via_usdc
                      - asset: ETH
                        calculated_at: 2026-05-01T10:00:00Z
                        change_24h: null
                        change_source: null
                        price: "3421.08"
                        price_source: binance:ws:via_usdc
                    quote_asset: USD
                    unavailable:
                      - asset: SOL
                        reason: unknown_pair
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: prices.assets
  /prices/indicative:
    get:
      description: "Returns the raw non-binding exchange pricing envelope for a
        from-asset/to-asset pair. Supply exactly the positive anchored amount:
        `from_amount` when `amount_basis=from`, or `to_amount` when
        `amount_basis=to`; omit the other amount. `indicative_price.price` is
        the to-asset amount per unit of from-asset. `account_ref` requires a
        bound enterprise or client operating scope; missing/platform bindings
        are refused with 403 and an account outside that scope is hidden with
        404. This response is informational only; execution must request pricing
        again."
      summary: Get indicative price
      tags:
        - Live Operations
        - Prices
      security:
        - BearerAuth: []
      parameters:
        - name: from_asset
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: to_asset
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: amount_basis
          in: query
          required: true
          schema:
            type: string
            enum:
              - from
              - to
        - name: from_amount
          in: query
          required: false
          schema:
            description: DecimalString
            type: string
            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
        - name: to_amount
          in: query
          required: false
          schema:
            description: DecimalString
            type: string
            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
        - name: account_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                amount_basis: from
                binding: false
                calculated_at: 2026-05-01T10:00:00Z
                expires_at: 2026-05-01T10:01:00.000Z
                flow_type: conversion
                from_amount:
                  currency: USDC
                  value: "250.00"
                from_asset: USDC
                indicative_price:
                  computed_at: 2026-05-01T10:00:00Z
                  price: "0.0000152"
                  price_type: indicative
                pricing_mode: indicative
                to_amount:
                  currency: BTC
                  value: "0.00380000"
                to_asset: BTC
              schema:
                required:
                  - flow_type
                  - pricing_mode
                  - amount_basis
                  - from_asset
                  - to_asset
                  - from_amount
                  - to_amount
                  - indicative_price
                  - calculated_at
                  - expires_at
                  - binding
                type: object
                additionalProperties: false
                properties:
                  amount_basis:
                    type: string
                    enum:
                      - from
                      - to
                  binding:
                    type: boolean
                    const: false
                  calculated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  flow_type:
                    type: string
                    const: conversion
                  from_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  from_asset:
                    type: string
                    minLength: 1
                  indicative_price:
                    required:
                      - price
                      - price_type
                      - computed_at
                    type: object
                    additionalProperties: false
                    properties:
                      computed_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      expires_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      price:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      price_type:
                        type: string
                        const: indicative
                      provider_hint:
                        anyOf:
                          - type: string
                          - type: "null"
                  pricing_mode:
                    type: string
                    const: indicative
                  to_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  to_asset:
                    type: string
                    minLength: 1
                examples:
                  - amount_basis: from
                    binding: false
                    calculated_at: 2026-05-01T10:00:00Z
                    expires_at: 2026-05-01T10:01:00.000Z
                    flow_type: conversion
                    from_amount:
                      currency: USDC
                      value: "250.00"
                    from_asset: USDC
                    indicative_price:
                      computed_at: 2026-05-01T10:00:00Z
                      price: "0.0000152"
                      price_type: indicative
                    pricing_mode: indicative
                    to_amount:
                      currency: BTC
                      value: "0.00380000"
                    to_asset: BTC
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: prices.indicative
  /production-access-requests:
    post:
      description: "Tells our compliance team that this sandbox tenant is ready to go
        live. Nothing is provisioned by the call and the sandbox tenant is
        unchanged: the two deployments are separate, so going live means a
        production account created for you by hand, and this is how we learn
        there is one to create. Requires a human user bound to an enterprise
        with a contact email. The company and contact address come from platform
        records; the optional note is the only body field, and the whole body
        may be omitted. A 200 means our team was reached; if they were not, the
        call fails with 503 and retrying is the right move. Asking again when
        you already have a request returns 409. The production deployment
        returns 409 with reason production_access_not_available."
      summary: Request production access
      tags:
        - Onboarding
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            example:
              note: We expect around 2,000 payouts a month across AR and BR, and we would like
                to be live before the end of the quarter.
            schema:
              type: object
              additionalProperties: false
              properties:
                note:
                  anyOf:
                    - type: string
                      maxLength: 2000
                    - type: "null"
              examples:
                - note: We expect around 2,000 payouts a month across AR and BR, and we would like
                    to be live before the end of the quarter.
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-04-19T12:00:00Z
                enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                notified: true
                production_access_request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                provisioned_at: null
              schema:
                required:
                  - production_access_request_id
                  - enterprise_ref
                  - notified
                  - created_at
                  - provisioned_at
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  enterprise_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  notified:
                    anyOf:
                      - type: boolean
                      - type: "null"
                  production_access_request_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  provisioned_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                examples:
                  - created_at: 2026-04-19T12:00:00Z
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    notified: true
                    production_access_request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    provisioned_at: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: production_access_requests.create
      x-required-capability:
        - kyc.verify
  /production-access-requests/current:
    get:
      description: "Where your request to go live stands. `production_access_request:
        null` means no announcement has reached compliance; failed announcement
        attempts are not shown. A request with `provisioned_at: null` means
        production provisioning has not been recorded, and `created_at` is the
        day you asked. A request with `provisioned_at` set means your production
        account exists. Answers for your bound enterprise under kyc.verify. The
        production deployment returns 409 with reason
        production_access_not_available."
      summary: Read the current production access request
      tags:
        - Onboarding
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                production_access_request:
                  created_at: 2026-04-19T12:00:00Z
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  notified: true
                  production_access_request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  provisioned_at: null
              schema:
                required:
                  - production_access_request
                type: object
                additionalProperties: false
                properties:
                  production_access_request:
                    anyOf:
                      - required:
                          - production_access_request_id
                          - enterprise_ref
                          - notified
                          - created_at
                          - provisioned_at
                        type: object
                        additionalProperties: false
                        properties:
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          enterprise_ref:
                            type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          notified:
                            anyOf:
                              - type: boolean
                              - type: "null"
                          production_access_request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          provisioned_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: "null"
                      - type: "null"
                examples:
                  - production_access_request:
                      created_at: 2026-04-19T12:00:00Z
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      notified: true
                      production_access_request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      provisioned_at: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: production_access_requests.current
      x-required-capability:
        - kyc.verify
  /role-assignments:
    get:
      summary: List role assignments
      tags:
        - Setup
        - Role Assignments
      security:
        - BearerAuth: []
      parameters:
        - name: principal_ref
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              - type: "null"
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: role_ref
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              - type: "null"
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - revoked
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - revoked
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: role_assignment
                    role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope_anchor_kind: explicit
                    scope_propagation: subtree
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - principal_ref
                        - role_ref
                        - scope_ref
                        - scope_anchor_kind
                        - scope_propagation
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        etag:
                          type: string
                          minLength: 1
                        granted_by:
                          anyOf:
                            - type: string
                              pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        principal_ref:
                          type: string
                          pattern: ^(users|service-accounts|system-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        resource:
                          type: string
                          const: role_assignment
                        role_ref:
                          type: string
                          pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        scope_anchor_kind:
                          type: string
                          enum:
                            - explicit
                            - enterprise_wildcard
                        scope_propagation:
                          type: string
                          enum:
                            - self
                            - subtree
                        scope_ref:
                          type: string
                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - revoked
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - created_at: 2026-05-01T10:00:00Z
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: role_assignment
                        role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        scope_anchor_kind: explicit
                        scope_propagation: subtree
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: role_assignments.list
      x-required-capability:
        - role_assignments.read
    post:
      description: "Requires Idempotency-Key and an active role visible for the
        requested scope. The grantor must hold role_assignments.create with at
        least the propagation reach being delegated. `scope_propagation`
        defaults to `subtree`; `self` reaches only the named scope. A user
        cannot receive a role carrying service-only capabilities. Seed-only
        roles cannot be granted through the API. At `platform-operators/<id>`
        scope a role that carries enterprise-governed capabilities needs an
        explicit `scope_anchor_kind`: `enterprise_wildcard` covers every
        enterprise, `explicit` covers the platform operator alone. Omitting it
        there is refused with `invalid_request` / `scope_anchor_kind_required`;
        at enterprise and client scope it defaults to `explicit`.
        `enterprise_wildcard` is allowed only at platform-operator scope,
        requires enterprise-governed permissions, and must use subtree
        propagation."
      summary: Grant role assignment
      tags:
        - Setup
        - Role Assignments
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Client-generated key, 1-128 characters. Accepted on POST requests
            and required where marked. For the same concrete path and
            caller/subject/tenant scope, an identical body replays the original
            status and body; a different body returns 409 idempotency_conflict.
            Keep query parameters unchanged when retrying.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            example:
              principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              scope_anchor_kind: explicit
              scope_propagation: subtree
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - principal_ref
                - role_ref
                - scope_ref
              type: object
              additionalProperties: false
              properties:
                principal_ref:
                  type: string
                  pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                role_ref:
                  type: string
                  pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                scope_anchor_kind:
                  type: string
                  enum:
                    - explicit
                    - enterprise_wildcard
                scope_propagation:
                  type: string
                  enum:
                    - self
                    - subtree
                scope_ref:
                  type: string
                  pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  scope_anchor_kind: explicit
                  scope_propagation: subtree
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: role_assignment
                role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                scope_anchor_kind: explicit
                scope_propagation: subtree
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - principal_ref
                  - role_ref
                  - scope_ref
                  - scope_anchor_kind
                  - scope_propagation
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  granted_by:
                    anyOf:
                      - type: string
                        pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_ref:
                    type: string
                    pattern: ^(users|service-accounts|system-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  resource:
                    type: string
                    const: role_assignment
                  role_ref:
                    type: string
                    pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  scope_anchor_kind:
                    type: string
                    enum:
                      - explicit
                      - enterprise_wildcard
                  scope_propagation:
                    type: string
                    enum:
                      - self
                      - subtree
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - revoked
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: role_assignment
                    role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope_anchor_kind: explicit
                    scope_propagation: subtree
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: role_assignments.create
      x-required-capability:
        - role_assignments.create
  /role-assignments/{role_assignment_id}:
    get:
      summary: Get role assignment
      tags:
        - Setup
        - Role Assignments
      security:
        - BearerAuth: []
      parameters:
        - name: role_assignment_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: role_assignment
                role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                scope_anchor_kind: explicit
                scope_propagation: subtree
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - principal_ref
                  - role_ref
                  - scope_ref
                  - scope_anchor_kind
                  - scope_propagation
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  granted_by:
                    anyOf:
                      - type: string
                        pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_ref:
                    type: string
                    pattern: ^(users|service-accounts|system-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  resource:
                    type: string
                    const: role_assignment
                  role_ref:
                    type: string
                    pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  scope_anchor_kind:
                    type: string
                    enum:
                      - explicit
                      - enterprise_wildcard
                  scope_propagation:
                    type: string
                    enum:
                      - self
                      - subtree
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - revoked
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: role_assignment
                    role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope_anchor_kind: explicit
                    scope_propagation: subtree
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: role_assignments.get
      x-required-capability:
        - role_assignments.read
  /role-assignments/{role_assignment_id}/revoke:
    post:
      description: "Revokes the assignment and returns status `revoked`; no If-Match
        header is required. An already revoked assignment returns 409. The final
        enterprise-scope assignment carrying role_assignments.manage cannot be
        revoked: grant another enterprise administrator first."
      summary: Revoke role assignment
      tags:
        - Setup
        - Role Assignments
      security:
        - BearerAuth: []
      parameters:
        - name: role_assignment_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: role_assignment
                role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                scope_anchor_kind: explicit
                scope_propagation: subtree
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: revoked
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - principal_ref
                  - role_ref
                  - scope_ref
                  - scope_anchor_kind
                  - scope_propagation
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  granted_by:
                    anyOf:
                      - type: string
                        pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_ref:
                    type: string
                    pattern: ^(users|service-accounts|system-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  resource:
                    type: string
                    const: role_assignment
                  role_ref:
                    type: string
                    pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  scope_anchor_kind:
                    type: string
                    enum:
                      - explicit
                      - enterprise_wildcard
                  scope_propagation:
                    type: string
                    enum:
                      - self
                      - subtree
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - revoked
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: role_assignment
                    role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope_anchor_kind: explicit
                    scope_propagation: subtree
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: revoked
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: role_assignments.revoke
      x-required-capability:
        - role_assignments.manage
  /roles:
    get:
      summary: List roles
      tags:
        - Setup
        - Roles
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - retired
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - retired
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - name: Enterprise Admin
                    description: Full administrative access within an enterprise
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    permissions:
                      - withdrawals.create
                      - deposits.read
                      - clients.read
                    platform_managed: false
                    resource: role
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - scope_ref
                        - platform_managed
                        - name
                        - description
                        - permissions
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        name:
                          type: string
                          minLength: 1
                        description:
                          anyOf:
                            - type: string
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        etag:
                          type: string
                          minLength: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        permissions:
                          type: array
                          items:
                            type: string
                            pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                            minLength: 1
                        platform_managed:
                          type: boolean
                        resource:
                          type: string
                          const: role
                        scope_ref:
                          anyOf:
                            - type: string
                              pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        status:
                          type: string
                          enum:
                            - active
                            - retired
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - name: Enterprise Admin
                        description: Full administrative access within an enterprise
                        created_at: 2026-05-01T10:00:00Z
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        permissions:
                          - withdrawals.create
                          - deposits.read
                          - clients.read
                        platform_managed: false
                        resource: role
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: roles.list
      x-required-capability:
        - roles.read
    post:
      description: "Creates a tenant-managed active role at the explicit topology
        scope. Requires Idempotency-Key. Permissions must use canonical
        capability names and suit the scope: platform-owned and
        platform-actor-only capabilities cannot be placed in an enterprise or
        client role. Seed-only capabilities cannot be granted through the API."
      summary: Create role
      tags:
        - Setup
        - Roles
      security:
        - BearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          description: Client-generated key, 1-128 characters. Accepted on POST requests
            and required where marked. For the same concrete path and
            caller/subject/tenant scope, an identical body replays the original
            status and body; a different body returns 409 idempotency_conflict.
            Keep query parameters unchanged when retrying.
          schema:
            type: string
            minLength: 1
            maxLength: 128
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Enterprise Admin
              description: Full administrative access within an enterprise
              permissions:
                - withdrawals.create
                - deposits.read
                - clients.read
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - scope_ref
                - name
                - permissions
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  minLength: 1
                description:
                  anyOf:
                    - type: string
                    - type: "null"
                permissions:
                  type: array
                  items:
                    type: string
                    enum:
                      - users.read
                      - users.invite
                      - users.create
                      - users.manage
                      - users.activate_federated
                      - users.recovery_initiate
                      - service_accounts.read
                      - service_accounts.create
                      - service_accounts.manage
                      - service_accounts.rotate_secret
                      - clients.read
                      - clients.create
                      - clients.manage
                      - accounts.read
                      - accounts.create
                      - accounts.manage
                      - roles.read
                      - roles.create
                      - roles.manage
                      - role_assignments.read
                      - role_assignments.create
                      - role_assignments.manage
                      - withdrawals.read
                      - withdrawals.create
                      - withdrawals.manage
                      - conversions.read
                      - conversions.create
                      - conversions.manage
                      - external_settlement_conversions.read
                      - external_settlement_conversions.create
                      - external_settlement_conversions.manage
                      - internal_transfers.read
                      - internal_transfers.create
                      - internal_transfers.manage
                      - ramps.read
                      - ramps.create
                      - ramps.manage
                      - policies.read
                      - policies.create
                      - policies.manage
                      - commercial_agreements.read
                      - commercial_agreements.create
                      - commercial_agreements.manage
                      - loans.read
                      - loans.create
                      - loans.manage
                      - loan_products.read
                      - loan_products.manage
                      - loan_shortfalls.read
                      - sandbox_simulator.run
                      - sandbox_reset.run
                      - webhooks.read
                      - webhooks.create
                      - webhooks.manage
                      - funding_endpoints.read
                      - funding_endpoints.provision
                      - deposit_instructions.read
                      - deposit_instructions.create
                      - withdrawal_destinations.read
                      - withdrawal_destinations.create
                      - withdrawal_destinations.manage
                      - deposits.read
                      - deposits.credit
                      - approvals.read
                      - approvals.decide
                      - compliance_assessments.read
                      - compliance_assessments.decide
                      - compliance_assessments.read_decision_volume
                      - compliance_assessments.reveal_subject_identity
                      - compliance_alerts.read
                      - compliance_alerts.acknowledge
                      - compliance_rules.read
                      - compliance_rules.manage
                      - events.read
                      - feature_flags.read
                      - feature_flags.manage
                      - feature_flags.manage_platform
                      - identity_providers.manage
                      - enterprises.read
                      - enterprises.list
                      - enterprises.create
                      - enterprises.provision
                      - enterprises.manage
                      - enterprises.restrict
                      - enterprises.reactivate
                      - enterprises.terminate
                      - kyc.verify
                      - payment_methods.manage
                      - payout_methods.manage
                      - crypto_networks.manage
                      - platform_operators.read
                      - platform_operators.manage
                      - platform_principals.manage
                      - platform_principals.rotate_secret
                      - ledger.compensate
                      - ledger.fee_post
                      - ledger.reconciliation_post
                      - overdraft_limits.manage
                      - operations_reports.read
                      - operations_reports.create_export
                      - operations_reports.view_fee_breakdown
                      - operations_reports.view_actor_attribution
                      - audit.read
                      - audit.create_export
                      - audit.view_technical_traces
                      - audit.view_actor_pii
                      - audit.view_free_text
                      - catalog.manage
                      - custody_mappings.manage
                      - onchain_analytics_mappings.manage
                      - fiat_routes.manage
                      - conversion_routes.manage
                      - settlement_bindings.manage
                      - legal.publish
                      - operations.review
                      - operations.recovery
                      - admissibility.read
                      - custody.read
                  minItems: 1
                scope_ref:
                  type: string
                  pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - name: Enterprise Admin
                  description: Full administrative access within an enterprise
                  permissions:
                    - withdrawals.create
                    - deposits.read
                    - clients.read
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                name: Enterprise Admin
                description: Full administrative access within an enterprise
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                permissions:
                  - withdrawals.create
                  - deposits.read
                  - clients.read
                platform_managed: false
                resource: role
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - platform_managed
                  - name
                  - description
                  - permissions
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  permissions:
                    type: array
                    items:
                      type: string
                      pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                      minLength: 1
                  platform_managed:
                    type: boolean
                  resource:
                    type: string
                    const: role
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - active
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - name: Enterprise Admin
                    description: Full administrative access within an enterprise
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    permissions:
                      - withdrawals.create
                      - deposits.read
                      - clients.read
                    platform_managed: false
                    resource: role
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: roles.create
      x-required-capability:
        - roles.create
  /roles/{role_id}:
    parameters:
      - name: role_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get role
      tags:
        - Setup
        - Roles
      security:
        - BearerAuth: []
      parameters:
        - name: role_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                name: Enterprise Admin
                description: Full administrative access within an enterprise
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                permissions:
                  - withdrawals.create
                  - deposits.read
                  - clients.read
                platform_managed: false
                resource: role
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - platform_managed
                  - name
                  - description
                  - permissions
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  permissions:
                    type: array
                    items:
                      type: string
                      pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                      minLength: 1
                  platform_managed:
                    type: boolean
                  resource:
                    type: string
                    const: role
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - active
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - name: Enterprise Admin
                    description: Full administrative access within an enterprise
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    permissions:
                      - withdrawals.create
                      - deposits.read
                      - clients.read
                    platform_managed: false
                    resource: role
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: roles.get
      x-required-capability:
        - roles.read
    patch:
      description: "Patches an active tenant-managed role. Requires the current
        `If-Match` entity tag. Platform-managed roles are immutable through this
        API; retired roles cannot be updated. Omitting a field preserves it;
        `description: null` clears the description, but `name: null` is refused.
        Permission changes invalidate affected principals’ authority context."
      summary: Update role
      tags:
        - Setup
        - Roles
      security:
        - BearerAuth: []
      parameters:
        - name: role_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            example:
              name: Updated Role Name
              description: Updated description
              permissions:
                - withdrawals.create
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  anyOf:
                    - type: string
                      minLength: 1
                    - type: "null"
                description:
                  anyOf:
                    - type: string
                    - type: "null"
                permissions:
                  type: array
                  items:
                    type: string
                    enum:
                      - users.read
                      - users.invite
                      - users.create
                      - users.manage
                      - users.activate_federated
                      - users.recovery_initiate
                      - service_accounts.read
                      - service_accounts.create
                      - service_accounts.manage
                      - service_accounts.rotate_secret
                      - clients.read
                      - clients.create
                      - clients.manage
                      - accounts.read
                      - accounts.create
                      - accounts.manage
                      - roles.read
                      - roles.create
                      - roles.manage
                      - role_assignments.read
                      - role_assignments.create
                      - role_assignments.manage
                      - withdrawals.read
                      - withdrawals.create
                      - withdrawals.manage
                      - conversions.read
                      - conversions.create
                      - conversions.manage
                      - external_settlement_conversions.read
                      - external_settlement_conversions.create
                      - external_settlement_conversions.manage
                      - internal_transfers.read
                      - internal_transfers.create
                      - internal_transfers.manage
                      - ramps.read
                      - ramps.create
                      - ramps.manage
                      - policies.read
                      - policies.create
                      - policies.manage
                      - commercial_agreements.read
                      - commercial_agreements.create
                      - commercial_agreements.manage
                      - loans.read
                      - loans.create
                      - loans.manage
                      - loan_products.read
                      - loan_products.manage
                      - loan_shortfalls.read
                      - sandbox_simulator.run
                      - sandbox_reset.run
                      - webhooks.read
                      - webhooks.create
                      - webhooks.manage
                      - funding_endpoints.read
                      - funding_endpoints.provision
                      - deposit_instructions.read
                      - deposit_instructions.create
                      - withdrawal_destinations.read
                      - withdrawal_destinations.create
                      - withdrawal_destinations.manage
                      - deposits.read
                      - deposits.credit
                      - approvals.read
                      - approvals.decide
                      - compliance_assessments.read
                      - compliance_assessments.decide
                      - compliance_assessments.read_decision_volume
                      - compliance_assessments.reveal_subject_identity
                      - compliance_alerts.read
                      - compliance_alerts.acknowledge
                      - compliance_rules.read
                      - compliance_rules.manage
                      - events.read
                      - feature_flags.read
                      - feature_flags.manage
                      - feature_flags.manage_platform
                      - identity_providers.manage
                      - enterprises.read
                      - enterprises.list
                      - enterprises.create
                      - enterprises.provision
                      - enterprises.manage
                      - enterprises.restrict
                      - enterprises.reactivate
                      - enterprises.terminate
                      - kyc.verify
                      - payment_methods.manage
                      - payout_methods.manage
                      - crypto_networks.manage
                      - platform_operators.read
                      - platform_operators.manage
                      - platform_principals.manage
                      - platform_principals.rotate_secret
                      - ledger.compensate
                      - ledger.fee_post
                      - ledger.reconciliation_post
                      - overdraft_limits.manage
                      - operations_reports.read
                      - operations_reports.create_export
                      - operations_reports.view_fee_breakdown
                      - operations_reports.view_actor_attribution
                      - audit.read
                      - audit.create_export
                      - audit.view_technical_traces
                      - audit.view_actor_pii
                      - audit.view_free_text
                      - catalog.manage
                      - custody_mappings.manage
                      - onchain_analytics_mappings.manage
                      - fiat_routes.manage
                      - conversion_routes.manage
                      - settlement_bindings.manage
                      - legal.publish
                      - operations.review
                      - operations.recovery
                      - admissibility.read
                      - custody.read
                  minItems: 1
              examples:
                - name: Updated Role Name
                  description: Updated description
                  permissions:
                    - withdrawals.create
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                name: Updated Role Name
                description: Updated description
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                permissions:
                  - withdrawals.create
                platform_managed: false
                resource: role
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - platform_managed
                  - name
                  - description
                  - permissions
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  permissions:
                    type: array
                    items:
                      type: string
                      pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                      minLength: 1
                  platform_managed:
                    type: boolean
                  resource:
                    type: string
                    const: role
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - active
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - name: Updated Role Name
                    description: Updated description
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    permissions:
                      - withdrawals.create
                    platform_managed: false
                    resource: role
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: roles.update
      x-required-capability:
        - roles.manage
  /roles/{role_id}/retire:
    post:
      description: Retires a tenant-managed role and returns status `retired`.
        Retiring an already retired role or a platform-managed role returns 409.
        This action does not require If-Match.
      summary: Retire role
      tags:
        - Setup
        - Roles
      security:
        - BearerAuth: []
      parameters:
        - name: role_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                name: Enterprise Admin
                description: Full administrative access within an enterprise
                created_at: 2026-05-01T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                permissions:
                  - withdrawals.create
                  - deposits.read
                  - clients.read
                platform_managed: false
                resource: role
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: retired
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - platform_managed
                  - name
                  - description
                  - permissions
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  name:
                    type: string
                    minLength: 1
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  etag:
                    type: string
                    minLength: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  permissions:
                    type: array
                    items:
                      type: string
                      pattern: ^[a-z0-9]+(?:[._][a-z0-9]+)*$
                      minLength: 1
                  platform_managed:
                    type: boolean
                  resource:
                    type: string
                    const: role
                  scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - active
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - name: Enterprise Admin
                    description: Full administrative access within an enterprise
                    created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    permissions:
                      - withdrawals.create
                      - deposits.read
                      - clients.read
                    platform_managed: false
                    resource: role
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: retired
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: roles.retire
      x-required-capability:
        - roles.manage
  /sandbox/clients/{client_id}/kyc-review:
    post:
      description: "Sandbox only: this route does not exist in production (404).
        Requires sandbox_simulator.run and visibility of the target. Use the
        same Idempotency-Key when retrying the same simulation; without a key,
        each call creates a new simulation. A 202 response accepts an
        asynchronous simulation; it does not mean the resource has reached its
        final state. Observe the ordinary resource reads and subscribed events.
        An unsupported simulation returns simulation_not_supported_for_route; a
        target that is not ready returns simulation_target_not_ready. Produces
        kyc.verification.reviewed.v1. The client must already have a
        verification session. Read GET /kyc/clients/{client_id}/status to follow
        the resulting verification state. Approved, rejected and
        resubmission_required represent the external review outcomes."
      summary: Simulate client verification review
      tags:
        - Sandbox
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              outcome: approved
            schema:
              required:
                - outcome
              type: object
              additionalProperties: false
              properties:
                outcome:
                  type: string
                  enum:
                    - approved
                    - rejected
                    - resubmission_required
              examples:
                - outcome: approved
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the affected
            resource and subscribed events; simulation_id is not an operation
            ID.
          content:
            application/json:
              example:
                accepted_at: 2026-05-01T10:00:00Z
                simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - simulation_id
                  - accepted_at
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  simulation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted_at: 2026-05-01T10:00:00Z
                    simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: sandbox.clients.kyc_review
      servers:
        - description: Sandbox
          url: https://b2b2x-sandbox.youhodler.com/api
      x-environment: sandbox
      x-required-capability:
        - sandbox_simulator.run
  /sandbox/enterprises/{enterprise_id}/kyb-review:
    post:
      description: "Sandbox only: this route does not exist in production (404).
        Requires sandbox_simulator.run and visibility of the target. Use the
        same Idempotency-Key when retrying the same simulation; without a key,
        each call creates a new simulation. A 202 response accepts an
        asynchronous simulation; it does not mean the resource has reached its
        final state. Observe the ordinary resource reads and subscribed events.
        An unsupported simulation returns simulation_not_supported_for_route; a
        target that is not ready returns simulation_target_not_ready. Produces
        kyc.verification.reviewed.v1 as reviews are processed. Reviews the
        caller's own enterprise. Start verification with POST /kyc/access-token
        first: an existing verification applicant is required. An approved
        outcome supplies synthetic business details and advances the
        verification stages. Read GET /kyc/flow and GET /kyc/status to follow
        completion; rejected and resubmission_required simulate the
        corresponding review outcomes."
      summary: Simulate enterprise verification review
      tags:
        - Sandbox
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              outcome: approved
            schema:
              required:
                - outcome
              type: object
              additionalProperties: false
              properties:
                outcome:
                  type: string
                  enum:
                    - approved
                    - rejected
                    - resubmission_required
              examples:
                - outcome: approved
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the affected
            resource and subscribed events; simulation_id is not an operation
            ID.
          content:
            application/json:
              example:
                accepted_at: 2026-05-01T10:00:00Z
                simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - simulation_id
                  - accepted_at
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  simulation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted_at: 2026-05-01T10:00:00Z
                    simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: sandbox.enterprises.kyb_review
      servers:
        - description: Sandbox
          url: https://b2b2x-sandbox.youhodler.com/api
      x-environment: sandbox
      x-required-capability:
        - sandbox_simulator.run
  /sandbox/funding-endpoints/{funding_endpoint_id}/incoming-transfers:
    post:
      description: "Sandbox only: this route does not exist in production (404).
        Requires sandbox_simulator.run and visibility of the target. Use the
        same Idempotency-Key when retrying the same simulation; without a key,
        each call creates a new simulation. A 202 response accepts an
        asynchronous simulation; it does not mean the resource has reached its
        final state. Observe the ordinary resource reads and subscribed events.
        An unsupported simulation returns simulation_not_supported_for_route; a
        target that is not ready returns simulation_target_not_ready. Observe
        rails.deposit.detected.v1 and operations.deposit.*.v1, including
        operations.deposit.settled.v1 after successful credit. The funding
        endpoint must receive the requested currency and belong to the named
        account. Use rail_class fiat or crypto; only fiat accepts reference.
        Follow GET /deposits and the credited account's balances. Screening,
        admission and other normal controls still apply: acceptance is not a
        guarantee of immediate credit."
      summary: Simulate an incoming transfer
      tags:
        - Sandbox
      security:
        - BearerAuth: []
      parameters:
        - name: funding_endpoint_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              amount:
                currency: USD
                value: "100.00"
              rail_class: fiat
              reference: Sandbox transfer
            schema:
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  amount:
                    currency: USD
                    value: "100.00"
                  rail_class: fiat
                  reference: Sandbox transfer
              oneOf:
                - required:
                    - rail_class
                    - account_ref
                    - amount
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    amount:
                      required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    rail_class:
                      type: string
                      const: fiat
                    reference:
                      anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 140
                        - type: "null"
                - required:
                    - rail_class
                    - account_ref
                    - amount
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    amount:
                      required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    rail_class:
                      type: string
                      const: crypto
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the affected
            resource and subscribed events; simulation_id is not an operation
            ID.
          content:
            application/json:
              example:
                accepted_at: 2026-05-01T10:00:00Z
                simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - simulation_id
                  - accepted_at
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  simulation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted_at: 2026-05-01T10:00:00Z
                    simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: sandbox.funding_endpoints.incoming_transfers
      servers:
        - description: Sandbox
          url: https://b2b2x-sandbox.youhodler.com/api
      x-environment: sandbox
      x-required-capability:
        - sandbox_simulator.run
  /sandbox/funding-endpoints/{funding_endpoint_id}/issuance-review:
    post:
      description: "Sandbox only: this route does not exist in production (404).
        Requires sandbox_simulator.run and visibility of the target. Use the
        same Idempotency-Key when retrying the same simulation; without a key,
        each call creates a new simulation. A 202 response accepts an
        asynchronous simulation; it does not mean the resource has reached its
        final state. Observe the ordinary resource reads and subscribed events.
        An unsupported simulation returns simulation_not_supported_for_route; a
        target that is not ready returns simulation_target_not_ready. There is
        no dedicated issuance webhook in the public event catalog; poll the
        resource. Decides a pending fiat account application or pending account
        feature. Crypto issuance review is unsupported. Read GET
        /funding-endpoints/{funding_endpoint_id} with the ordinary account_ref
        and rail_class query parameters until issuance resolves."
      summary: Simulate funding endpoint issuance review
      tags:
        - Sandbox
      security:
        - BearerAuth: []
      parameters:
        - name: funding_endpoint_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              outcome: approved
              rail_class: fiat
            schema:
              required:
                - rail_class
                - account_ref
                - outcome
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                outcome:
                  type: string
                  enum:
                    - approved
                    - rejected
                rail_class:
                  type: string
                  enum:
                    - fiat
                    - crypto
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  outcome: approved
                  rail_class: fiat
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the affected
            resource and subscribed events; simulation_id is not an operation
            ID.
          content:
            application/json:
              example:
                accepted_at: 2026-05-01T10:00:00Z
                simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - simulation_id
                  - accepted_at
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  simulation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted_at: 2026-05-01T10:00:00Z
                    simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: sandbox.funding_endpoints.issuance_review
      servers:
        - description: Sandbox
          url: https://b2b2x-sandbox.youhodler.com/api
      x-environment: sandbox
      x-required-capability:
        - sandbox_simulator.run
  /sandbox/withdrawal-destinations/{destination_id}/review:
    post:
      description: "Sandbox only: this route does not exist in production (404).
        Requires sandbox_simulator.run and visibility of the target. Use the
        same Idempotency-Key when retrying the same simulation; without a key,
        each call creates a new simulation. A 202 response accepts an
        asynchronous simulation; it does not mean the resource has reached its
        final state. Observe the ordinary resource reads and subscribed events.
        An unsupported simulation returns simulation_not_supported_for_route; a
        target that is not ready returns simulation_target_not_ready. There is
        no dedicated destination-review webhook in the public event catalog;
        poll the resource. Decides the external review of a fiat withdrawal
        destination. Read GET /withdrawal-destinations/{destination_id} with its
        account_ref and rail_class to follow the resulting state."
      summary: Simulate withdrawal destination review
      tags:
        - Sandbox
      security:
        - BearerAuth: []
      parameters:
        - name: destination_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              outcome: approved
            schema:
              required:
                - account_ref
                - outcome
              type: object
              additionalProperties: false
              properties:
                account_ref:
                  type: string
                  pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                outcome:
                  type: string
                  enum:
                    - approved
                    - rejected
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  outcome: approved
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the affected
            resource and subscribed events; simulation_id is not an operation
            ID.
          content:
            application/json:
              example:
                accepted_at: 2026-05-01T10:00:00Z
                simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - simulation_id
                  - accepted_at
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  simulation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted_at: 2026-05-01T10:00:00Z
                    simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: sandbox.withdrawal_destinations.review
      servers:
        - description: Sandbox
          url: https://b2b2x-sandbox.youhodler.com/api
      x-environment: sandbox
      x-required-capability:
        - sandbox_simulator.run
  /sandbox/withdrawals/{withdrawal_id}/settlement:
    post:
      description: "Sandbox only: this route does not exist in production (404).
        Requires sandbox_simulator.run and visibility of the target. Use the
        same Idempotency-Key when retrying the same simulation; without a key,
        each call creates a new simulation. A 202 response accepts an
        asynchronous simulation; it does not mean the resource has reached its
        final state. Observe the ordinary resource reads and subscribed events.
        An unsupported simulation returns simulation_not_supported_for_route; a
        target that is not ready returns simulation_target_not_ready. Observe
        operations.withdrawal.settled.v1 or operations.withdrawal.failed.v1. The
        fiat withdrawal must already have been dispatched. Use settled or failed
        and, for a failure, an optional reason. Crypto withdrawals and
        already-final withdrawals are unsupported. Follow GET
        /withdrawals/{withdrawal_id} and its normal operation events."
      summary: Simulate withdrawal settlement
      tags:
        - Sandbox
      security:
        - BearerAuth: []
      parameters:
        - name: withdrawal_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              outcome: settled
            schema:
              required:
                - outcome
              type: object
              additionalProperties: false
              properties:
                outcome:
                  type: string
                  enum:
                    - settled
                    - failed
                reason:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 140
                    - type: "null"
              examples:
                - outcome: settled
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the affected
            resource and subscribed events; simulation_id is not an operation
            ID.
          content:
            application/json:
              example:
                accepted_at: 2026-05-01T10:00:00Z
                simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - simulation_id
                  - accepted_at
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  simulation_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted_at: 2026-05-01T10:00:00Z
                    simulation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: sandbox.withdrawals.settlement
      servers:
        - description: Sandbox
          url: https://b2b2x-sandbox.youhodler.com/api
      x-environment: sandbox
      x-required-capability:
        - sandbox_simulator.run
  /service-accounts:
    get:
      summary: List service accounts
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: parent_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - revoked
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - revoked
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - description: Withdrawal automation account
                    created_at: 2026-05-01T10:00:00Z
                    current_secret_expires_at: 2026-05-02T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    external_id: sa-ext-001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    managed_by: null
                    parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    previous_secret_expires_at: null
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: service_account
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - parent_ref
                        - principal_ref
                        - description
                        - external_id
                        - managed_by
                        - current_secret_expires_at
                        - previous_secret_expires_at
                        - created_at
                        - updated_at
                        - etag
                      description: Public service account resource. The account itself has no expiry;
                        only client secrets and access tokens have independent
                        TTLs.
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          anyOf:
                            - type: string
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        current_secret_expires_at:
                          description: Expiry of the currently active client secret, or null for an
                            account with no secret (an enterprise backend
                            authenticating with private_key_jwt). The service
                            account itself never expires on a timer, and JWT
                            access-token TTL is separate.
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        etag:
                          type: string
                          minLength: 1
                        external_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          description: Stable service account identifier. Matches `client_id` and the
                            trailing id segment of `principal_ref`.
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        managed_by:
                          description: Identity provider that manages this system account; null for
                            tenant-created accounts. Managed accounts cannot be
                            revoked or have their secret rotated through the
                            service-account API.
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        parent_ref:
                          type: string
                          pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        previous_secret_expires_at:
                          description: Expiry of the previous client secret during a rotation grace
                            window, or null when no previous secret remains
                            valid.
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        principal_ref:
                          description: principal_ref ≡ service-accounts/{client_id} ≡
                            service-accounts/{id}
                          type: string
                          pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        resource:
                          type: string
                          const: service_account
                        status:
                          description: "Service accounts do not expire on a timer. Lifecycle is
                            status-only: `active` or `revoked`."
                          type: string
                          enum:
                            - active
                            - revoked
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - description: Withdrawal automation account
                        created_at: 2026-05-01T10:00:00Z
                        current_secret_expires_at: 2026-05-02T10:00:00Z
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        external_id: sa-ext-001
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        managed_by: null
                        parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        previous_secret_expires_at: null
                        principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: service_account
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.list
      x-required-capability:
        - service_accounts.read
    post:
      description: Creates a service account and mints a fresh `client_secret`. The
        plaintext secret is returned in this issuance response; ordinary reads
        do not return it. Store it immediately. A retry with the same
        Idempotency-Key returns the account created by the first request,
        without its `client_secret`, instead of creating a second one. Use
        `service_accounts.rotate_secret` to issue a new secret if the original
        response was lost. The service account itself never expires on a timer;
        lifecycle is status-only (`active` or `revoked`).
        `client_secret_expires_at` is the client-secret TTL, while JWT
        access-token TTL is separate. `client_secret_ttl_seconds` is optional,
        has a minimum of 60 seconds and no maximum; omission uses the deployment
        default. The parent must be an enterprise or client. Managed accounts
        (`managed_by` is non-null) cannot be revoked or rotated here.
      summary: Create service account
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              description: Withdrawal automation account
              external_id: sa-ext-001
              parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - parent_ref
              type: object
              additionalProperties: false
              properties:
                description:
                  anyOf:
                    - type: string
                    - type: "null"
                client_secret_ttl_seconds:
                  type: integer
                  minimum: 60
                  maximum: 9007199254740991
                external_id:
                  anyOf:
                    - type: string
                    - type: "null"
                parent_ref:
                  type: string
                  pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - description: Withdrawal automation account
                  external_id: sa-ext-001
                  parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                client_secret: cs_live_abc123placeholder
                client_secret_expires_at: 2026-05-02T10:00:00Z
                principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                service_account:
                  description: Withdrawal automation account
                  created_at: 2026-05-01T10:00:00Z
                  current_secret_expires_at: 2026-05-02T10:00:00Z
                  etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                  external_id: sa-ext-001
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  managed_by: null
                  parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  previous_secret_expires_at: null
                  principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  resource: service_account
                  status: active
                  updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - service_account
                  - client_id
                  - client_secret_expires_at
                  - principal_ref
                type: object
                additionalProperties: false
                properties:
                  client_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  client_secret:
                    description: Present only in the first response. A retry with the same
                      Idempotency-Key replays the response without it.
                    type: string
                    minLength: 1
                  client_secret_expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  principal_ref:
                    type: string
                    pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  service_account:
                    required:
                      - id
                      - resource
                      - status
                      - parent_ref
                      - principal_ref
                      - description
                      - external_id
                      - managed_by
                      - current_secret_expires_at
                      - previous_secret_expires_at
                      - created_at
                      - updated_at
                      - etag
                    description: Public service account resource. The account itself has no expiry;
                      only client secrets and access tokens have independent
                      TTLs.
                    type: object
                    additionalProperties: false
                    properties:
                      description:
                        anyOf:
                          - type: string
                          - type: "null"
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      current_secret_expires_at:
                        description: Expiry of the currently active client secret, or null for an
                          account with no secret (an enterprise backend
                          authenticating with private_key_jwt). The service
                          account itself never expires on a timer, and JWT
                          access-token TTL is separate.
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      etag:
                        type: string
                        minLength: 1
                      external_id:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        description: Stable service account identifier. Matches `client_id` and the
                          trailing id segment of `principal_ref`.
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      managed_by:
                        description: Identity provider that manages this system account; null for
                          tenant-created accounts. Managed accounts cannot be
                          revoked or have their secret rotated through the
                          service-account API.
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      parent_ref:
                        type: string
                        pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      previous_secret_expires_at:
                        description: Expiry of the previous client secret during a rotation grace
                          window, or null when no previous secret remains valid.
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      principal_ref:
                        description: principal_ref ≡ service-accounts/{client_id} ≡
                          service-accounts/{id}
                        type: string
                        pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      resource:
                        type: string
                        const: service_account
                      status:
                        description: "Service accounts do not expire on a timer. Lifecycle is
                          status-only: `active` or `revoked`."
                        type: string
                        enum:
                          - active
                          - revoked
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                examples:
                  - client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    client_secret: cs_live_abc123placeholder
                    client_secret_expires_at: 2026-05-02T10:00:00Z
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    service_account:
                      description: Withdrawal automation account
                      created_at: 2026-05-01T10:00:00Z
                      current_secret_expires_at: 2026-05-02T10:00:00Z
                      etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                      external_id: sa-ext-001
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      managed_by: null
                      parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      previous_secret_expires_at: null
                      principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      resource: service_account
                      status: active
                      updated_at: 2026-05-01T10:00:00Z
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.create
      x-required-capability:
        - service_accounts.create
  /service-accounts/{service_account_id}:
    parameters:
      - name: service_account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get service account
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: service_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                description: Withdrawal automation account
                created_at: 2026-05-01T10:00:00Z
                current_secret_expires_at: 2026-05-02T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                external_id: sa-ext-001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                managed_by: null
                parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                previous_secret_expires_at: null
                principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: service_account
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - parent_ref
                  - principal_ref
                  - description
                  - external_id
                  - managed_by
                  - current_secret_expires_at
                  - previous_secret_expires_at
                  - created_at
                  - updated_at
                  - etag
                description: Public service account resource. The account itself has no expiry;
                  only client secrets and access tokens have independent TTLs.
                type: object
                additionalProperties: false
                properties:
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  current_secret_expires_at:
                    description: Expiry of the currently active client secret, or null for an
                      account with no secret (an enterprise backend
                      authenticating with private_key_jwt). The service account
                      itself never expires on a timer, and JWT access-token TTL
                      is separate.
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    description: Stable service account identifier. Matches `client_id` and the
                      trailing id segment of `principal_ref`.
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  managed_by:
                    description: Identity provider that manages this system account; null for
                      tenant-created accounts. Managed accounts cannot be
                      revoked or have their secret rotated through the
                      service-account API.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  parent_ref:
                    type: string
                    pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  previous_secret_expires_at:
                    description: Expiry of the previous client secret during a rotation grace
                      window, or null when no previous secret remains valid.
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  principal_ref:
                    description: principal_ref ≡ service-accounts/{client_id} ≡
                      service-accounts/{id}
                    type: string
                    pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  resource:
                    type: string
                    const: service_account
                  status:
                    description: "Service accounts do not expire on a timer. Lifecycle is
                      status-only: `active` or `revoked`."
                    type: string
                    enum:
                      - active
                      - revoked
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - description: Withdrawal automation account
                    created_at: 2026-05-01T10:00:00Z
                    current_secret_expires_at: 2026-05-02T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    external_id: sa-ext-001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    managed_by: null
                    parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    previous_secret_expires_at: null
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: service_account
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.get
      x-required-capability:
        - service_accounts.read
    patch:
      description: Patch a service account. Requires `If-Match` from the resource GET
        response header. The body `etag` is the raw storage version; the HTTP
        `ETag` wraps that value as a weak entity tag.
      summary: Update service account
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: service_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            example:
              description: Updated description
            schema:
              type: object
              additionalProperties: false
              properties:
                description:
                  anyOf:
                    - type: string
                    - type: "null"
                external_id:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - description: Updated description
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                description: Withdrawal automation account
                created_at: 2026-05-01T10:00:00Z
                current_secret_expires_at: 2026-05-02T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                external_id: sa-ext-001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                managed_by: null
                parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                previous_secret_expires_at: null
                principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: service_account
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - parent_ref
                  - principal_ref
                  - description
                  - external_id
                  - managed_by
                  - current_secret_expires_at
                  - previous_secret_expires_at
                  - created_at
                  - updated_at
                  - etag
                description: Public service account resource. The account itself has no expiry;
                  only client secrets and access tokens have independent TTLs.
                type: object
                additionalProperties: false
                properties:
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  current_secret_expires_at:
                    description: Expiry of the currently active client secret, or null for an
                      account with no secret (an enterprise backend
                      authenticating with private_key_jwt). The service account
                      itself never expires on a timer, and JWT access-token TTL
                      is separate.
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    description: Stable service account identifier. Matches `client_id` and the
                      trailing id segment of `principal_ref`.
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  managed_by:
                    description: Identity provider that manages this system account; null for
                      tenant-created accounts. Managed accounts cannot be
                      revoked or have their secret rotated through the
                      service-account API.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  parent_ref:
                    type: string
                    pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  previous_secret_expires_at:
                    description: Expiry of the previous client secret during a rotation grace
                      window, or null when no previous secret remains valid.
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  principal_ref:
                    description: principal_ref ≡ service-accounts/{client_id} ≡
                      service-accounts/{id}
                    type: string
                    pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  resource:
                    type: string
                    const: service_account
                  status:
                    description: "Service accounts do not expire on a timer. Lifecycle is
                      status-only: `active` or `revoked`."
                    type: string
                    enum:
                      - active
                      - revoked
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - description: Withdrawal automation account
                    created_at: 2026-05-01T10:00:00Z
                    current_secret_expires_at: 2026-05-02T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    external_id: sa-ext-001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    managed_by: null
                    parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    previous_secret_expires_at: null
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: service_account
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.update
      x-required-capability:
        - service_accounts.manage
  /service-accounts/{service_account_id}/revoke:
    post:
      summary: Revoke service account
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: service_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                description: Withdrawal automation account
                created_at: 2026-05-01T10:00:00Z
                current_secret_expires_at: 2026-05-02T10:00:00Z
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                external_id: sa-ext-001
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                managed_by: null
                parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                previous_secret_expires_at: null
                principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource: service_account
                status: revoked
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - parent_ref
                  - principal_ref
                  - description
                  - external_id
                  - managed_by
                  - current_secret_expires_at
                  - previous_secret_expires_at
                  - created_at
                  - updated_at
                  - etag
                description: Public service account resource. The account itself has no expiry;
                  only client secrets and access tokens have independent TTLs.
                type: object
                additionalProperties: false
                properties:
                  description:
                    anyOf:
                      - type: string
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  current_secret_expires_at:
                    description: Expiry of the currently active client secret, or null for an
                      account with no secret (an enterprise backend
                      authenticating with private_key_jwt). The service account
                      itself never expires on a timer, and JWT access-token TTL
                      is separate.
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  external_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    description: Stable service account identifier. Matches `client_id` and the
                      trailing id segment of `principal_ref`.
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  managed_by:
                    description: Identity provider that manages this system account; null for
                      tenant-created accounts. Managed accounts cannot be
                      revoked or have their secret rotated through the
                      service-account API.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  parent_ref:
                    type: string
                    pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  previous_secret_expires_at:
                    description: Expiry of the previous client secret during a rotation grace
                      window, or null when no previous secret remains valid.
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  principal_ref:
                    description: principal_ref ≡ service-accounts/{client_id} ≡
                      service-accounts/{id}
                    type: string
                    pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  resource:
                    type: string
                    const: service_account
                  status:
                    description: "Service accounts do not expire on a timer. Lifecycle is
                      status-only: `active` or `revoked`."
                    type: string
                    enum:
                      - active
                      - revoked
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - description: Withdrawal automation account
                    created_at: 2026-05-01T10:00:00Z
                    current_secret_expires_at: 2026-05-02T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    external_id: sa-ext-001
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    managed_by: null
                    parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    previous_secret_expires_at: null
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: service_account
                    status: revoked
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.revoke
      x-required-capability:
        - service_accounts.manage
  /service-accounts/{service_account_id}/rotate-secret:
    post:
      description: "Issues a new `client_secret` with HTTP 201. The plaintext is
        returned only in this issuance response; ordinary reads do not return
        it. Rotation is not replayed: repeating the request issues a new secret,
        even with the same Idempotency-Key. By default the previous secret is
        invalidated immediately; pass `invalidate_previous_secret: false` to
        keep the immediately previous secret valid until its original expiry;
        rotation does not extend that expiry. Only one previous secret is
        retained. The service account itself never expires on a timer; lifecycle
        is status-only (`active` or `revoked`). `client_secret_expires_at` is
        the new client-secret TTL, while JWT access-token TTL is separate. The
        body may be omitted; omitted or null invalidate_previous_secret means
        true. `client_secret_ttl_seconds` is optional, at least 60 seconds, and
        has no upper bound; omission uses the deployment default. Revoked and
        managed accounts cannot be rotated."
      summary: Rotate service account secret
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - name: service_account_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: false
        content:
          application/json:
            example:
              invalidate_previous_secret: true
              reason: Routine rotation
            schema:
              type: object
              additionalProperties: false
              properties:
                client_secret_ttl_seconds:
                  type: integer
                  minimum: 60
                  maximum: 9007199254740991
                invalidate_previous_secret:
                  anyOf:
                    - type: boolean
                    - type: "null"
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
              examples:
                - invalidate_previous_secret: true
                  reason: Routine rotation
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                client_secret: cs_live_abc123placeholder
                client_secret_expires_at: 2026-05-02T10:00:00Z
                principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                service_account:
                  description: Withdrawal automation account
                  created_at: 2026-05-01T10:00:00Z
                  current_secret_expires_at: 2026-05-02T10:00:00Z
                  etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                  external_id: sa-ext-001
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  managed_by: null
                  parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  previous_secret_expires_at: null
                  principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  resource: service_account
                  status: active
                  updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - service_account
                  - client_id
                  - client_secret
                  - client_secret_expires_at
                  - principal_ref
                type: object
                additionalProperties: false
                properties:
                  client_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  client_secret:
                    type: string
                    minLength: 1
                  client_secret_expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  principal_ref:
                    type: string
                    pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  service_account:
                    required:
                      - id
                      - resource
                      - status
                      - parent_ref
                      - principal_ref
                      - description
                      - external_id
                      - managed_by
                      - current_secret_expires_at
                      - previous_secret_expires_at
                      - created_at
                      - updated_at
                      - etag
                    description: Public service account resource. The account itself has no expiry;
                      only client secrets and access tokens have independent
                      TTLs.
                    type: object
                    additionalProperties: false
                    properties:
                      description:
                        anyOf:
                          - type: string
                          - type: "null"
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      current_secret_expires_at:
                        description: Expiry of the currently active client secret, or null for an
                          account with no secret (an enterprise backend
                          authenticating with private_key_jwt). The service
                          account itself never expires on a timer, and JWT
                          access-token TTL is separate.
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      etag:
                        type: string
                        minLength: 1
                      external_id:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        description: Stable service account identifier. Matches `client_id` and the
                          trailing id segment of `principal_ref`.
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      managed_by:
                        description: Identity provider that manages this system account; null for
                          tenant-created accounts. Managed accounts cannot be
                          revoked or have their secret rotated through the
                          service-account API.
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      parent_ref:
                        type: string
                        pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      previous_secret_expires_at:
                        description: Expiry of the previous client secret during a rotation grace
                          window, or null when no previous secret remains valid.
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      principal_ref:
                        description: principal_ref ≡ service-accounts/{client_id} ≡
                          service-accounts/{id}
                        type: string
                        pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      resource:
                        type: string
                        const: service_account
                      status:
                        description: "Service accounts do not expire on a timer. Lifecycle is
                          status-only: `active` or `revoked`."
                        type: string
                        enum:
                          - active
                          - revoked
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                examples:
                  - client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    client_secret: cs_live_abc123placeholder
                    client_secret_expires_at: 2026-05-02T10:00:00Z
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    service_account:
                      description: Withdrawal automation account
                      created_at: 2026-05-01T10:00:00Z
                      current_secret_expires_at: 2026-05-02T10:00:00Z
                      etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                      external_id: sa-ext-001
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      managed_by: null
                      parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      previous_secret_expires_at: null
                      principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      resource: service_account
                      status: active
                      updated_at: 2026-05-01T10:00:00Z
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.rotate_secret
      x-required-capability:
        - service_accounts.rotate_secret
  /service-accounts/provision:
    post:
      description: "Creates a service account and grants it the supplied roles in a
        single call. Equivalent to `POST /service-accounts` followed by N ×
        `POST /role-assignments`, but saves the client the round-trips.
        Best-effort grant phase: the service account is always created if
        `identity-service` accepts it; per-role grant failures are reported in
        `role_assignment_errors` (preserving the input order) and the response
        is still `201`. The plaintext secret is included only in the issuance
        response; ordinary reads do not return it. Store it before retrying
        failed grants. A retry with the same Idempotency-Key returns the first
        response without its `client_secret` and creates or grants nothing
        again; use `service_accounts.rotate_secret` if the original response was
        lost. `client_secret_ttl_seconds` has a minimum of 60 seconds, no upper
        bound, and uses the deployment default when omitted."
      summary: Provision service account with roles
      tags:
        - Setup
        - Service Accounts
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              description: Withdrawal automation account
              parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              roles:
                - role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - parent_ref
                - roles
              type: object
              additionalProperties: false
              properties:
                description:
                  anyOf:
                    - type: string
                    - type: "null"
                client_secret_ttl_seconds:
                  type: integer
                  minimum: 60
                  maximum: 9007199254740991
                external_id:
                  anyOf:
                    - type: string
                    - type: "null"
                parent_ref:
                  type: string
                  pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                roles:
                  type: array
                  items:
                    required:
                      - role_ref
                      - scope_ref
                    type: object
                    additionalProperties: false
                    properties:
                      role_ref:
                        type: string
                        pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      scope_anchor_kind:
                        type: string
                        enum:
                          - explicit
                          - enterprise_wildcard
                      scope_propagation:
                        type: string
                        enum:
                          - self
                          - subtree
                      scope_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  minItems: 1
              examples:
                - description: Withdrawal automation account
                  parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  roles:
                    - role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                client_secret: cs_live_abc123placeholder
                client_secret_expires_at: 2026-05-02T10:00:00Z
                principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                role_assignment_errors: []
                role_assignments:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: role_assignment
                    role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope_anchor_kind: explicit
                    scope_propagation: subtree
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                service_account:
                  description: Withdrawal automation account
                  created_at: 2026-05-01T10:00:00Z
                  current_secret_expires_at: 2026-05-02T10:00:00Z
                  etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                  external_id: sa-ext-001
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  managed_by: null
                  parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  previous_secret_expires_at: null
                  principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  resource: service_account
                  status: active
                  updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - service_account
                  - client_id
                  - client_secret_expires_at
                  - principal_ref
                  - role_assignments
                  - role_assignment_errors
                type: object
                additionalProperties: false
                properties:
                  client_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  client_secret:
                    description: Present only in the first response. A retry with the same
                      Idempotency-Key replays the response without it.
                    type: string
                    minLength: 1
                  client_secret_expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  principal_ref:
                    type: string
                    pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  role_assignment_errors:
                    type: array
                    items:
                      required:
                        - role_ref
                        - scope_ref
                        - code
                        - message
                      type: object
                      additionalProperties: false
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        role_ref:
                          type: string
                        scope_ref:
                          type: string
                  role_assignments:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - principal_ref
                        - role_ref
                        - scope_ref
                        - scope_anchor_kind
                        - scope_propagation
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        etag:
                          type: string
                          minLength: 1
                        granted_by:
                          anyOf:
                            - type: string
                              pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        principal_ref:
                          type: string
                          pattern: ^(users|service-accounts|system-principals)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        resource:
                          type: string
                          const: role_assignment
                        role_ref:
                          type: string
                          pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        scope_anchor_kind:
                          type: string
                          enum:
                            - explicit
                            - enterprise_wildcard
                        scope_propagation:
                          type: string
                          enum:
                            - self
                            - subtree
                        scope_ref:
                          type: string
                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - revoked
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  service_account:
                    required:
                      - id
                      - resource
                      - status
                      - parent_ref
                      - principal_ref
                      - description
                      - external_id
                      - managed_by
                      - current_secret_expires_at
                      - previous_secret_expires_at
                      - created_at
                      - updated_at
                      - etag
                    description: Public service account resource. The account itself has no expiry;
                      only client secrets and access tokens have independent
                      TTLs.
                    type: object
                    additionalProperties: false
                    properties:
                      description:
                        anyOf:
                          - type: string
                          - type: "null"
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      current_secret_expires_at:
                        description: Expiry of the currently active client secret, or null for an
                          account with no secret (an enterprise backend
                          authenticating with private_key_jwt). The service
                          account itself never expires on a timer, and JWT
                          access-token TTL is separate.
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      etag:
                        type: string
                        minLength: 1
                      external_id:
                        anyOf:
                          - type: string
                          - type: "null"
                      id:
                        description: Stable service account identifier. Matches `client_id` and the
                          trailing id segment of `principal_ref`.
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      managed_by:
                        description: Identity provider that manages this system account; null for
                          tenant-created accounts. Managed accounts cannot be
                          revoked or have their secret rotated through the
                          service-account API.
                        anyOf:
                          - type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          - type: "null"
                      parent_ref:
                        type: string
                        pattern: ^(enterprises|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      previous_secret_expires_at:
                        description: Expiry of the previous client secret during a rotation grace
                          window, or null when no previous secret remains valid.
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      principal_ref:
                        description: principal_ref ≡ service-accounts/{client_id} ≡
                          service-accounts/{id}
                        type: string
                        pattern: ^(service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      resource:
                        type: string
                        const: service_account
                      status:
                        description: "Service accounts do not expire on a timer. Lifecycle is
                          status-only: `active` or `revoked`."
                        type: string
                        enum:
                          - active
                          - revoked
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                examples:
                  - client_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    client_secret: cs_live_abc123placeholder
                    client_secret_expires_at: 2026-05-02T10:00:00Z
                    principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    role_assignment_errors: []
                    role_assignments:
                      - created_at: 2026-05-01T10:00:00Z
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: role_assignment
                        role_ref: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        scope_anchor_kind: explicit
                        scope_propagation: subtree
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    service_account:
                      description: Withdrawal automation account
                      created_at: 2026-05-01T10:00:00Z
                      current_secret_expires_at: 2026-05-02T10:00:00Z
                      etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                      external_id: sa-ext-001
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      managed_by: null
                      parent_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      previous_secret_expires_at: null
                      principal_ref: service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      resource: service_account
                      status: active
                      updated_at: 2026-05-01T10:00:00Z
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: service_accounts.provision
      x-required-capability:
        - service_accounts.create
        - role_assignments.create
  /user-action-audit-entries/{entry_id}:
    get:
      summary: Get audit log entry
      tags:
        - Audit
        - User Action Audit Entries
      security:
        - BearerAuth: []
      parameters:
        - name: entry_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                action_family: tenant_governance
                approval_state: not_required
                attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    kind: user
                    ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    kind: user
                    ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                changed_fields: null
                correlation_id: null
                detail: null
                event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                event_type: tenant.enterprise.admitted.v1
                human_actor_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                occurred_at_utc: 2026-05-01T10:00:00Z
                reason_code: null
                reason_text: null
                recorded_at_utc: 2026-05-01T10:00:00Z
                request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                resource_type: enterprise
                result_status: succeeded
                scope:
                  client_account_ref: null
                  client_ref: null
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  master_account_ref: null
                  platform_operator_ref: null
                service_account_id: null
                source_service: edge-service
                trace_id: null
              schema:
                required:
                  - id
                  - event_id
                  - event_type
                  - action_family
                  - attribution
                  - scope
                  - resource_ref
                  - resource_type
                  - approval_state
                  - result_status
                  - reason_code
                  - reason_text
                  - changed_fields
                  - service_account_id
                  - human_actor_id
                  - request_id
                  - trace_id
                  - correlation_id
                  - source_service
                  - detail
                  - occurred_at_utc
                  - recorded_at_utc
                type: object
                additionalProperties: false
                properties:
                  action_family:
                    anyOf:
                      - type: string
                        enum:
                          - human_actor_lifecycle
                          - role_assignment
                          - policy_change
                          - service_account_governance
                          - webhook_subscription_governance
                          - financial_operation_audit
                          - tenant_governance
                          - approval_decision
                          - authentication
                          - other
                      - type: "null"
                  approval_state:
                    anyOf:
                      - type: string
                        enum:
                          - not_required
                          - pending
                          - approved
                          - rejected
                          - cancelled
                          - expired
                      - type: "null"
                  attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - kind
                              - ref
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              ref:
                                type: string
                                pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - kind
                              - ref
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              ref:
                                type: string
                                pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      authenticated_principal:
                        required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          ref:
                            type: string
                            pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - kind
                              - ref
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              ref:
                                type: string
                                pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - kind
                              - ref
                            type: object
                            additionalProperties: false
                            properties:
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              ref:
                                type: string
                                pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                  changed_fields:
                    anyOf:
                      - type: array
                        items:
                          required:
                            - name
                            - before
                            - after
                          type: object
                          additionalProperties: false
                          properties:
                            name:
                              type: string
                              minLength: 1
                            after: {}
                            before: {}
                      - type: "null"
                  correlation_id:
                    anyOf:
                      - type: string
                      - type: "null"
                  detail:
                    anyOf:
                      - type: object
                        additionalProperties: {}
                        propertyNames:
                          type: string
                      - type: "null"
                  event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  event_type:
                    type: string
                    pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
                  human_actor_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  occurred_at_utc:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  reason_code:
                    anyOf:
                      - type: string
                      - type: "null"
                  reason_text:
                    anyOf:
                      - type: string
                      - type: "null"
                  recorded_at_utc:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  request_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  resource_type:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  result_status:
                    type: string
                    enum:
                      - succeeded
                      - failed
                      - denied
                      - rejected
                      - cancelled
                  scope:
                    required:
                      - enterprise_ref
                      - platform_operator_ref
                      - master_account_ref
                      - client_ref
                      - client_account_ref
                    type: object
                    additionalProperties: false
                    properties:
                      client_account_ref:
                        anyOf:
                          - type: string
                            pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      client_ref:
                        anyOf:
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      enterprise_ref:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      master_account_ref:
                        anyOf:
                          - type: string
                            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                      platform_operator_ref:
                        anyOf:
                          - type: string
                            pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: "null"
                  service_account_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  source_service:
                    type: string
                    minLength: 1
                  trace_id:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - action_family: tenant_governance
                    approval_state: not_required
                    attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        kind: user
                        ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        kind: user
                        ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    changed_fields: null
                    correlation_id: null
                    detail: null
                    event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    event_type: tenant.enterprise.admitted.v1
                    human_actor_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    occurred_at_utc: 2026-05-01T10:00:00Z
                    reason_code: null
                    reason_text: null
                    recorded_at_utc: 2026-05-01T10:00:00Z
                    request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource_type: enterprise
                    result_status: succeeded
                    scope:
                      client_account_ref: null
                      client_ref: null
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      master_account_ref: null
                      platform_operator_ref: null
                    service_account_id: null
                    source_service: edge-service
                    trace_id: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_action_audit_entries.get
      x-required-capability:
        - audit.read
  /user-action-audit-entries/search:
    get:
      description: Queries the immutable audit trail. occurred_from_utc and
        occurred_to_utc are required and must form a strictly increasing range.
        Supply at least one enterprise_ref, master_account_ref, client_ref or
        client_account_ref covered by audit.read, or use cross_scope=true with
        platform-wide audit.read authority. Cross-scope searches cannot include
        those scope filters. Multi-value event_types, action_families,
        result_statuses and reason_codes accept repeated query values or a
        single comma-separated value. limit defaults to 100, with range 1..500;
        offset defaults to 0 and must be nonnegative.
      summary: Search audit log entries
      tags:
        - Audit
        - User Action Audit Entries
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: master_account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: client_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: client_account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: authenticated_principal
          in: query
          required: false
          schema:
            type: string
            pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: subject
          in: query
          required: false
          schema:
            type: string
            pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: actor
          in: query
          required: false
          schema:
            type: string
            pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: resource_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: subject_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: actor_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: cross_scope
          in: query
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: string
                enum:
                  - "true"
                  - "false"
        - name: source_service
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: event_types
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
              - type: array
                items:
                  type: string
                  pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
        - name: action_families
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - human_actor_lifecycle
                  - role_assignment
                  - policy_change
                  - service_account_governance
                  - webhook_subscription_governance
                  - financial_operation_audit
                  - tenant_governance
                  - approval_decision
                  - authentication
                  - other
              - type: array
                items:
                  type: string
                  enum:
                    - human_actor_lifecycle
                    - role_assignment
                    - policy_change
                    - service_account_governance
                    - webhook_subscription_governance
                    - financial_operation_audit
                    - tenant_governance
                    - approval_decision
                    - authentication
                    - other
        - name: result_statuses
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - succeeded
                  - failed
                  - denied
                  - rejected
                  - cancelled
              - type: array
                items:
                  type: string
                  enum:
                    - succeeded
                    - failed
                    - denied
                    - rejected
                    - cancelled
        - name: reason_codes
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                minLength: 1
              - type: array
                items:
                  type: string
                  minLength: 1
        - name: occurred_from_utc
          in: query
          required: true
          schema:
            anyOf:
              - type: string
                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                format: date-time
              - type: string
                format: date-time
        - name: occurred_to_utc
          in: query
          required: true
          schema:
            anyOf:
              - type: string
                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                format: date-time
              - type: string
                format: date-time
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 9007199254740991
            default: 0
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - action_family: tenant_governance
                    approval_state: not_required
                    attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        kind: user
                        ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        kind: user
                        ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    changed_fields: null
                    correlation_id: null
                    detail: null
                    event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    event_type: tenant.enterprise.admitted.v1
                    human_actor_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    occurred_at_utc: 2026-05-01T10:00:00Z
                    reason_code: null
                    reason_text: null
                    recorded_at_utc: 2026-05-01T10:00:00Z
                    request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource_type: enterprise
                    result_status: succeeded
                    scope:
                      client_account_ref: null
                      client_ref: null
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      master_account_ref: null
                      platform_operator_ref: null
                    service_account_id: null
                    source_service: edge-service
                    trace_id: null
                limit: 100
                offset: 0
                total: 1
              schema:
                required:
                  - items
                  - total
                  - limit
                  - offset
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - event_id
                        - event_type
                        - action_family
                        - attribution
                        - scope
                        - resource_ref
                        - resource_type
                        - approval_state
                        - result_status
                        - reason_code
                        - reason_text
                        - changed_fields
                        - service_account_id
                        - human_actor_id
                        - request_id
                        - trace_id
                        - correlation_id
                        - source_service
                        - detail
                        - occurred_at_utc
                        - recorded_at_utc
                      type: object
                      additionalProperties: false
                      properties:
                        action_family:
                          anyOf:
                            - type: string
                              enum:
                                - human_actor_lifecycle
                                - role_assignment
                                - policy_change
                                - service_account_governance
                                - webhook_subscription_governance
                                - financial_operation_audit
                                - tenant_governance
                                - approval_decision
                                - authentication
                                - other
                            - type: "null"
                        approval_state:
                          anyOf:
                            - type: string
                              enum:
                                - not_required
                                - pending
                                - approved
                                - rejected
                                - cancelled
                                - expired
                            - type: "null"
                        attribution:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - kind
                                    - ref
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    ref:
                                      type: string
                                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - kind
                                    - ref
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    ref:
                                      type: string
                                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            authenticated_principal:
                              required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                ref:
                                  type: string
                                  pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - kind
                                    - ref
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    ref:
                                      type: string
                                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - kind
                                    - ref
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    ref:
                                      type: string
                                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                        changed_fields:
                          anyOf:
                            - type: array
                              items:
                                required:
                                  - name
                                  - before
                                  - after
                                type: object
                                additionalProperties: false
                                properties:
                                  name:
                                    type: string
                                    minLength: 1
                                  after: {}
                                  before: {}
                            - type: "null"
                        correlation_id:
                          anyOf:
                            - type: string
                            - type: "null"
                        detail:
                          anyOf:
                            - type: object
                              additionalProperties: {}
                              propertyNames:
                                type: string
                            - type: "null"
                        event_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        event_type:
                          type: string
                          pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
                        human_actor_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        occurred_at_utc:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        reason_code:
                          anyOf:
                            - type: string
                            - type: "null"
                        reason_text:
                          anyOf:
                            - type: string
                            - type: "null"
                        recorded_at_utc:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        request_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        resource_ref:
                          anyOf:
                            - type: string
                              pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        resource_type:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        result_status:
                          type: string
                          enum:
                            - succeeded
                            - failed
                            - denied
                            - rejected
                            - cancelled
                        scope:
                          required:
                            - enterprise_ref
                            - platform_operator_ref
                            - master_account_ref
                            - client_ref
                            - client_account_ref
                          type: object
                          additionalProperties: false
                          properties:
                            client_account_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            client_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            enterprise_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            master_account_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                            platform_operator_ref:
                              anyOf:
                                - type: string
                                  pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                - type: "null"
                        service_account_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        source_service:
                          type: string
                          minLength: 1
                        trace_id:
                          anyOf:
                            - type: string
                            - type: "null"
                  limit:
                    type: integer
                    maximum: 9007199254740991
                    exclusiveMinimum: 0
                  offset:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  total:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                examples:
                  - items:
                      - action_family: tenant_governance
                        approval_state: not_required
                        attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            kind: user
                            ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            kind: user
                            ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        changed_fields: null
                        correlation_id: null
                        detail: null
                        event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        event_type: tenant.enterprise.admitted.v1
                        human_actor_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        occurred_at_utc: 2026-05-01T10:00:00Z
                        reason_code: null
                        reason_text: null
                        recorded_at_utc: 2026-05-01T10:00:00Z
                        request_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource_type: enterprise
                        result_status: succeeded
                        scope:
                          client_account_ref: null
                          client_ref: null
                          enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          master_account_ref: null
                          platform_operator_ref: null
                        service_account_id: null
                        source_service: edge-service
                        trace_id: null
                    limit: 100
                    offset: 0
                    total: 1
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_action_audit_entries.search
      x-required-capability:
        - audit.read
  /user-action-audit-exports:
    get:
      description: Lists exports created by the current actor that remain covered by
        audit.read, with an optional status filter. limit defaults to 50 and is
        bounded 1..200. The response is an items array without cursor
        pagination.
      summary: List audit exports
      tags:
        - Audit
        - User Action Audit Exports
      security:
        - BearerAuth: []
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - queued
              - running
              - ready
              - failed
              - expired
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - format: csv
                    byte_size: 8192
                    download_path: /user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                    expires_at_utc: 2026-05-02T10:00:00Z
                    failure_reason: null
                    filter_criteria:
                      occurred_from_utc: 2026-04-01T00:00:00Z
                      occurred_to_utc: 2026-04-30T23:59:59Z
                    finished_at_utc: 2026-05-01T10:00:00Z
                    generated_at_utc: 2026-05-01T10:00:00Z
                    generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requested_scope:
                      kind: enterprise
                      ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    row_count: 42
                    status: ready
                    storage_location: null
              schema:
                required:
                  - items
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - status
                        - format
                        - requested_scope
                        - filter_criteria
                        - generated_by
                        - generated_at_utc
                        - finished_at_utc
                        - expires_at_utc
                        - row_count
                        - byte_size
                        - storage_location
                        - download_path
                        - failure_reason
                      type: object
                      additionalProperties: false
                      properties:
                        format:
                          type: string
                          enum:
                            - csv
                            - json
                        byte_size:
                          anyOf:
                            - type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            - type: "null"
                        download_path:
                          anyOf:
                            - type: string
                            - type: "null"
                        expires_at_utc:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        failure_reason:
                          anyOf:
                            - type: string
                            - type: "null"
                        filter_criteria:
                          required:
                            - occurred_from_utc
                            - occurred_to_utc
                          type: object
                          additionalProperties: false
                          properties:
                            action_families:
                              type: array
                              items:
                                type: string
                                enum:
                                  - human_actor_lifecycle
                                  - role_assignment
                                  - policy_change
                                  - service_account_governance
                                  - webhook_subscription_governance
                                  - financial_operation_audit
                                  - tenant_governance
                                  - approval_decision
                                  - authentication
                                  - other
                            actor:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            authenticated_principal:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            event_types:
                              type: array
                              items:
                                type: string
                                pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
                            occurred_from_utc:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            occurred_to_utc:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            reason_codes:
                              type: array
                              items:
                                type: string
                                minLength: 1
                            resource_ref:
                              type: string
                              pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            result_statuses:
                              type: array
                              items:
                                type: string
                                enum:
                                  - succeeded
                                  - failed
                                  - denied
                                  - rejected
                                  - cancelled
                            subject:
                              type: string
                              pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        finished_at_utc:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        generated_at_utc:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        generated_by:
                          type: string
                          pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        requested_scope:
                          oneOf:
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: enterprise
                                ref:
                                  type: string
                                  pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: master_account
                                ref:
                                  type: string
                                  pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: client
                                ref:
                                  type: string
                                  pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: client_account
                                ref:
                                  type: string
                                  pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - required:
                                - kind
                                - ref
                              type: object
                              additionalProperties: false
                              properties:
                                kind:
                                  type: string
                                  const: platform_operator
                                ref:
                                  type: string
                                  pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        row_count:
                          anyOf:
                            - type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            - type: "null"
                        status:
                          type: string
                          enum:
                            - queued
                            - running
                            - ready
                            - failed
                            - expired
                        storage_location:
                          anyOf:
                            - type: string
                            - type: "null"
                examples:
                  - items:
                      - format: csv
                        byte_size: 8192
                        download_path: /user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                        expires_at_utc: 2026-05-02T10:00:00Z
                        failure_reason: null
                        filter_criteria:
                          occurred_from_utc: 2026-04-01T00:00:00Z
                          occurred_to_utc: 2026-04-30T23:59:59Z
                        finished_at_utc: 2026-05-01T10:00:00Z
                        generated_at_utc: 2026-05-01T10:00:00Z
                        generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        requested_scope:
                          kind: enterprise
                          ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        row_count: 42
                        status: ready
                        storage_location: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_action_audit_exports.list
      x-required-capability:
        - audit.read
    post:
      description: Creates a scope-bound audit export with format csv or json. The
        json format streams newline-delimited JSON. Inspect status and
        download_path for readiness; storage_location is always null and clients
        download through the relative gateway path. Export list, get and
        download are limited to the creating actor and current audit.read
        coverage of the stored requested_scope.
      summary: Create audit export
      tags:
        - Audit
        - User Action Audit Exports
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              format: csv
              filter_criteria:
                occurred_from_utc: 2026-04-01T00:00:00Z
                occurred_to_utc: 2026-04-30T23:59:59Z
              requested_scope:
                kind: enterprise
                ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - format
                - requested_scope
                - filter_criteria
              type: object
              additionalProperties: false
              properties:
                format:
                  type: string
                  enum:
                    - csv
                    - json
                filter_criteria:
                  required:
                    - occurred_from_utc
                    - occurred_to_utc
                  type: object
                  additionalProperties: false
                  properties:
                    action_families:
                      type: array
                      items:
                        type: string
                        enum:
                          - human_actor_lifecycle
                          - role_assignment
                          - policy_change
                          - service_account_governance
                          - webhook_subscription_governance
                          - financial_operation_audit
                          - tenant_governance
                          - approval_decision
                          - authentication
                          - other
                    actor:
                      type: string
                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    authenticated_principal:
                      type: string
                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    event_types:
                      type: array
                      items:
                        type: string
                        pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
                    occurred_from_utc:
                      anyOf:
                        - type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        - type: string
                          format: date-time
                    occurred_to_utc:
                      anyOf:
                        - type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        - type: string
                          format: date-time
                    reason_codes:
                      type: array
                      items:
                        type: string
                        minLength: 1
                    resource_ref:
                      type: string
                      pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    result_statuses:
                      type: array
                      items:
                        type: string
                        enum:
                          - succeeded
                          - failed
                          - denied
                          - rejected
                          - cancelled
                    subject:
                      type: string
                      pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                requested_scope:
                  oneOf:
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: enterprise
                        ref:
                          type: string
                          pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: master_account
                        ref:
                          type: string
                          pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: client
                        ref:
                          type: string
                          pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: client_account
                        ref:
                          type: string
                          pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - required:
                        - kind
                        - ref
                      type: object
                      additionalProperties: false
                      properties:
                        kind:
                          type: string
                          const: platform_operator
                        ref:
                          type: string
                          pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - format: csv
                  filter_criteria:
                    occurred_from_utc: 2026-04-01T00:00:00Z
                    occurred_to_utc: 2026-04-30T23:59:59Z
                  requested_scope:
                    kind: enterprise
                    ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                format: csv
                byte_size: 8192
                download_path: /user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                expires_at_utc: 2026-05-02T10:00:00Z
                failure_reason: null
                filter_criteria:
                  occurred_from_utc: 2026-04-01T00:00:00Z
                  occurred_to_utc: 2026-04-30T23:59:59Z
                finished_at_utc: 2026-05-01T10:00:00Z
                generated_at_utc: 2026-05-01T10:00:00Z
                generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requested_scope:
                  kind: enterprise
                  ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                row_count: 42
                status: ready
                storage_location: null
              schema:
                required:
                  - id
                  - status
                  - format
                  - requested_scope
                  - filter_criteria
                  - generated_by
                  - generated_at_utc
                  - finished_at_utc
                  - expires_at_utc
                  - row_count
                  - byte_size
                  - storage_location
                  - download_path
                  - failure_reason
                type: object
                additionalProperties: false
                properties:
                  format:
                    type: string
                    enum:
                      - csv
                      - json
                  byte_size:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  download_path:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  filter_criteria:
                    required:
                      - occurred_from_utc
                      - occurred_to_utc
                    type: object
                    additionalProperties: false
                    properties:
                      action_families:
                        type: array
                        items:
                          type: string
                          enum:
                            - human_actor_lifecycle
                            - role_assignment
                            - policy_change
                            - service_account_governance
                            - webhook_subscription_governance
                            - financial_operation_audit
                            - tenant_governance
                            - approval_decision
                            - authentication
                            - other
                      actor:
                        type: string
                        pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      authenticated_principal:
                        type: string
                        pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      event_types:
                        type: array
                        items:
                          type: string
                          pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
                      occurred_from_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      occurred_to_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      reason_codes:
                        type: array
                        items:
                          type: string
                          minLength: 1
                      resource_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      result_statuses:
                        type: array
                        items:
                          type: string
                          enum:
                            - succeeded
                            - failed
                            - denied
                            - rejected
                            - cancelled
                      subject:
                        type: string
                        pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  finished_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  generated_at_utc:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  generated_by:
                    type: string
                    pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requested_scope:
                    oneOf:
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: enterprise
                          ref:
                            type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: master_account
                          ref:
                            type: string
                            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client
                          ref:
                            type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client_account
                          ref:
                            type: string
                            pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: platform_operator
                          ref:
                            type: string
                            pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  row_count:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - ready
                      - failed
                      - expired
                  storage_location:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - format: csv
                    byte_size: 8192
                    download_path: /user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                    expires_at_utc: 2026-05-02T10:00:00Z
                    failure_reason: null
                    filter_criteria:
                      occurred_from_utc: 2026-04-01T00:00:00Z
                      occurred_to_utc: 2026-04-30T23:59:59Z
                    finished_at_utc: 2026-05-01T10:00:00Z
                    generated_at_utc: 2026-05-01T10:00:00Z
                    generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requested_scope:
                      kind: enterprise
                      ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    row_count: 42
                    status: ready
                    storage_location: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_action_audit_exports.create
      x-required-capability:
        - audit.create_export
  /user-action-audit-exports/{export_id}:
    get:
      description: Reads an export belonging to the current actor and covered by
        audit.read. A hidden or missing export returns 404. download_path is
        null until ready and after expiry.
      summary: Get audit export
      tags:
        - Audit
        - User Action Audit Exports
      security:
        - BearerAuth: []
      parameters:
        - name: export_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                format: csv
                byte_size: 8192
                download_path: /user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                expires_at_utc: 2026-05-02T10:00:00Z
                failure_reason: null
                filter_criteria:
                  occurred_from_utc: 2026-04-01T00:00:00Z
                  occurred_to_utc: 2026-04-30T23:59:59Z
                finished_at_utc: 2026-05-01T10:00:00Z
                generated_at_utc: 2026-05-01T10:00:00Z
                generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                requested_scope:
                  kind: enterprise
                  ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                row_count: 42
                status: ready
                storage_location: null
              schema:
                required:
                  - id
                  - status
                  - format
                  - requested_scope
                  - filter_criteria
                  - generated_by
                  - generated_at_utc
                  - finished_at_utc
                  - expires_at_utc
                  - row_count
                  - byte_size
                  - storage_location
                  - download_path
                  - failure_reason
                type: object
                additionalProperties: false
                properties:
                  format:
                    type: string
                    enum:
                      - csv
                      - json
                  byte_size:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  download_path:
                    anyOf:
                      - type: string
                      - type: "null"
                  expires_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                      - type: "null"
                  filter_criteria:
                    required:
                      - occurred_from_utc
                      - occurred_to_utc
                    type: object
                    additionalProperties: false
                    properties:
                      action_families:
                        type: array
                        items:
                          type: string
                          enum:
                            - human_actor_lifecycle
                            - role_assignment
                            - policy_change
                            - service_account_governance
                            - webhook_subscription_governance
                            - financial_operation_audit
                            - tenant_governance
                            - approval_decision
                            - authentication
                            - other
                      actor:
                        type: string
                        pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      authenticated_principal:
                        type: string
                        pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      event_types:
                        type: array
                        items:
                          type: string
                          pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2,3}$
                      occurred_from_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      occurred_to_utc:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      reason_codes:
                        type: array
                        items:
                          type: string
                          minLength: 1
                      resource_ref:
                        type: string
                        pattern: ^(enterprises|platform-operators|clients|master-accounts|client-accounts|users|service-accounts|platform-principals|identity-providers|roles|role-assignments|system-principals|commercial-agreements|policy-rules|operations|compliance-assessments|webhook-subscriptions)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      result_statuses:
                        type: array
                        items:
                          type: string
                          enum:
                            - succeeded
                            - failed
                            - denied
                            - rejected
                            - cancelled
                      subject:
                        type: string
                        pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  finished_at_utc:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  generated_at_utc:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  generated_by:
                    type: string
                    pattern: ^(users|service-accounts|platform-principals|identity-providers)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  requested_scope:
                    oneOf:
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: enterprise
                          ref:
                            type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: master_account
                          ref:
                            type: string
                            pattern: ^(master-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client
                          ref:
                            type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: client_account
                          ref:
                            type: string
                            pattern: ^(client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - required:
                          - kind
                          - ref
                        type: object
                        additionalProperties: false
                        properties:
                          kind:
                            type: string
                            const: platform_operator
                          ref:
                            type: string
                            pattern: ^(platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  row_count:
                    anyOf:
                      - type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - ready
                      - failed
                      - expired
                  storage_location:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - format: csv
                    byte_size: 8192
                    download_path: /user-action-audit-exports/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b/download
                    expires_at_utc: 2026-05-02T10:00:00Z
                    failure_reason: null
                    filter_criteria:
                      occurred_from_utc: 2026-04-01T00:00:00Z
                      occurred_to_utc: 2026-04-30T23:59:59Z
                    finished_at_utc: 2026-05-01T10:00:00Z
                    generated_at_utc: 2026-05-01T10:00:00Z
                    generated_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    requested_scope:
                      kind: enterprise
                      ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    row_count: 42
                    status: ready
                    storage_location: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_action_audit_exports.get
      x-required-capability:
        - audit.read
  /user-action-audit-exports/{export_id}/download:
    get:
      description: "Streams the ready export through edge. csv yields text/csv and
        json yields application/x-ndjson: one JSON object per line, with UTF-8
        encoding. Content-Type, Content-Disposition and optional Content-Length
        are forwarded from the download service. Unavailable, expired or hidden
        exports return 404; an unsuccessful upstream response other than 404
        returns 502."
      summary: Download audit export file
      tags:
        - Audit
        - User Action Audit Exports
      security:
        - BearerAuth: []
      parameters:
        - name: export_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/x-ndjson:
              schema:
                description: UTF-8 newline-delimited JSON, one ActionAuditEntry object per line.
                type: string
            text/csv:
              schema:
                description: UTF-8 CSV file with a header row.
                type: string
          headers:
            Content-Disposition:
              schema:
                type: string
            Content-Length:
              schema:
                type: string
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_action_audit_exports.download
      x-required-capability:
        - audit.read
  /user-invitations:
    get:
      description: Lists user invitations under an enterprise scope.
      summary: List user invitations
      tags:
        - Setup
        - User Invitations
      security:
        - BearerAuth: []
      parameters:
        - name: enterprise_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - pending
                  - accepting
                  - accepted
                  - expired
                  - cancelled
              - type: array
                items:
                  type: string
                  enum:
                    - pending
                    - accepting
                    - accepted
                    - expired
                    - cancelled
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - accepted_at: null
                    cancelled_at: null
                    created_at: 2026-05-01T10:00:00Z
                    email_constraint: jane.doe@acme.example
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    expires_at: 2026-05-02T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: pending
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - status
                        - enterprise_ref
                        - scope
                        - email_constraint
                        - role
                        - pending_human_actor_ref
                        - invited_by
                        - expires_at
                        - accepted_at
                        - cancelled_at
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        accepted_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        cancelled_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        email_constraint:
                          type: string
                          pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                          maxLength: 254
                          format: email
                        enterprise_ref:
                          type: string
                          pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        etag:
                          type: string
                          minLength: 1
                        expires_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        invited_by:
                          type: string
                          pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        pending_human_actor_ref:
                          type: string
                          pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        role:
                          type: string
                          pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        scope:
                          anyOf:
                            - type: string
                              pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: string
                              pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - pending
                            - accepting
                            - accepted
                            - expired
                            - cancelled
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - accepted_at: null
                        cancelled_at: null
                        created_at: 2026-05-01T10:00:00Z
                        email_constraint: jane.doe@acme.example
                        enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        expires_at: 2026-05-02T10:00:00Z
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: pending
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_invitations.list
      x-required-capability:
        - users.read
    post:
      description: Reserves a pending user and grants its role immediately; the
        assignment becomes usable when the actor is activated. The inviter must
        belong to the owning enterprise and be allowed to grant the selected
        role over the scope subtree. An existing pending invitation for the same
        scope and email is refreshed and returns status `resent`. When no
        pending invitation exists and that email already belongs to a user under
        the selected scope, creation returns `409 state_conflict` with
        `data.reason=email_already_used_under_parent`; it does not add an
        invitation to an existing active user. Hosted first access sends the
        one-time challenge only in a magic-link email; public invitation
        responses never include challenge_ref. `enterprise_idp` first access
        creates no hosted challenge or email and completes through `POST
        /users/{user_id}/activate-federated`.
      summary: Create user invitation
      tags:
        - Setup
        - User Invitations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              display_name: Jane Doe
              email: jane.doe@acme.example
              role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - email
                - role
                - scope
              type: object
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - type: string
                      minLength: 1
                      maxLength: 255
                    - type: "null"
                email:
                  type: string
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  maxLength: 254
                  format: email
                role:
                  type: string
                  pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                scope:
                  anyOf:
                    - type: string
                      pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - type: string
                      pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - display_name: Jane Doe
                  email: jane.doe@acme.example
                  role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                invitation:
                  accepted_at: null
                  cancelled_at: null
                  created_at: 2026-05-01T10:00:00Z
                  email_constraint: jane.doe@acme.example
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                  expires_at: 2026-05-02T10:00:00Z
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  status: pending
                  updated_at: 2026-05-01T10:00:00Z
                status: pending
              schema:
                required:
                  - invitation
                  - status
                type: object
                additionalProperties: false
                properties:
                  invitation:
                    required:
                      - id
                      - status
                      - enterprise_ref
                      - scope
                      - email_constraint
                      - role
                      - pending_human_actor_ref
                      - invited_by
                      - expires_at
                      - accepted_at
                      - cancelled_at
                      - created_at
                      - updated_at
                      - etag
                    type: object
                    additionalProperties: false
                    properties:
                      accepted_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      cancelled_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      email_constraint:
                        type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        maxLength: 254
                        format: email
                      enterprise_ref:
                        type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      etag:
                        type: string
                        minLength: 1
                      expires_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      invited_by:
                        type: string
                        pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      pending_human_actor_ref:
                        type: string
                        pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      role:
                        type: string
                        pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      scope:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      status:
                        type: string
                        enum:
                          - pending
                          - accepting
                          - accepted
                          - expired
                          - cancelled
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                  status:
                    type: string
                    enum:
                      - pending
                      - resent
                examples:
                  - invitation:
                      accepted_at: null
                      cancelled_at: null
                      created_at: 2026-05-01T10:00:00Z
                      email_constraint: jane.doe@acme.example
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                      expires_at: 2026-05-02T10:00:00Z
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      status: pending
                      updated_at: 2026-05-01T10:00:00Z
                    status: pending
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_invitations.create
      x-required-capability:
        - users.invite
  /user-invitations/{invitation_id}:
    get:
      summary: Get user invitation
      tags:
        - Setup
        - User Invitations
      security:
        - BearerAuth: []
      parameters:
        - name: invitation_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                accepted_at: null
                cancelled_at: null
                created_at: 2026-05-01T10:00:00Z
                email_constraint: jane.doe@acme.example
                enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                expires_at: 2026-05-02T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: pending
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - status
                  - enterprise_ref
                  - scope
                  - email_constraint
                  - role
                  - pending_human_actor_ref
                  - invited_by
                  - expires_at
                  - accepted_at
                  - cancelled_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  cancelled_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  email_constraint:
                    type: string
                    pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                    maxLength: 254
                    format: email
                  enterprise_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  etag:
                    type: string
                    minLength: 1
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  invited_by:
                    type: string
                    pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  pending_human_actor_ref:
                    type: string
                    pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  role:
                    type: string
                    pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  scope:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - pending
                      - accepting
                      - accepted
                      - expired
                      - cancelled
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - accepted_at: null
                    cancelled_at: null
                    created_at: 2026-05-01T10:00:00Z
                    email_constraint: jane.doe@acme.example
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    expires_at: 2026-05-02T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: pending
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_invitations.get
      x-required-capability:
        - users.read
  /user-invitations/accept:
    post:
      description: "Public hosted-accept endpoint: no Bearer token is required. Submit
        `invitation_id` and the one-time `challenge_ref` from the magic-link
        email. Accept activates the reserved user and its already-granted role
        and returns an accepted invitation plus a short-lived `session_token`.
        This credential response is never cached or replayed, even with
        Idempotency-Key, and the challenge is single-use: repeating an accept
        that already succeeded, for example after the response was lost, returns
        `409 state_conflict` with `data.reason=invitation_already_terminal`
        instead of a second session. The account is already active, so the user
        signs in normally instead. That token is a federated session assertion:
        exchange it as `subject_token` at `POST /oauth/token` with
        `grant_type=urn:ietf:params:oauth:grant-type:token-exchange` before
        calling protected API routes. Production returns `409 state_conflict`
        with `data.reason=not_supported`; enterprise_idp first access uses `POST
        /users/{user_id}/activate-federated` instead."
      summary: Accept user invitation
      tags:
        - Setup
        - User Invitations
      security: []
      requestBody:
        required: true
        content:
          application/json:
            example:
              challenge_ref: challenge-ref-0001
              invitation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - invitation_id
                - challenge_ref
              type: object
              additionalProperties: false
              properties:
                challenge_ref:
                  type: string
                  minLength: 1
                  maxLength: 256
                invitation_id:
                  type: string
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  format: uuid
              examples:
                - challenge_ref: challenge-ref-0001
                  invitation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                actor_scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                invitation:
                  accepted_at: 2026-05-01T10:00:00Z
                  cancelled_at: null
                  created_at: 2026-05-01T10:00:00Z
                  email_constraint: jane.doe@acme.example
                  enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                  expires_at: 2026-05-02T10:00:00Z
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  status: accepted
                  updated_at: 2026-05-01T10:00:00Z
                session_expires_at: 2026-05-01T11:00:00Z
                session_token: sess_eyJhbGciOiJSUzI1NiJ9.payload.sig
              schema:
                required:
                  - invitation
                  - session_token
                  - session_expires_at
                  - enterprise_ref
                  - actor_scope_ref
                type: object
                additionalProperties: false
                properties:
                  actor_scope_ref:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  enterprise_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  invitation:
                    required:
                      - id
                      - status
                      - enterprise_ref
                      - scope
                      - email_constraint
                      - role
                      - pending_human_actor_ref
                      - invited_by
                      - expires_at
                      - accepted_at
                      - cancelled_at
                      - created_at
                      - updated_at
                      - etag
                    type: object
                    additionalProperties: false
                    properties:
                      accepted_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      cancelled_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: "null"
                      created_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      email_constraint:
                        type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        maxLength: 254
                        format: email
                      enterprise_ref:
                        type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      etag:
                        type: string
                        minLength: 1
                      expires_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      invited_by:
                        type: string
                        pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      pending_human_actor_ref:
                        type: string
                        pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      role:
                        type: string
                        pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      scope:
                        anyOf:
                          - type: string
                            pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                          - type: string
                            pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      status:
                        type: string
                        enum:
                          - pending
                          - accepting
                          - accepted
                          - expired
                          - cancelled
                      updated_at:
                        type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                  session_expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  session_token:
                    type: string
                    minLength: 1
                examples:
                  - actor_scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    invitation:
                      accepted_at: 2026-05-01T10:00:00Z
                      cancelled_at: null
                      created_at: 2026-05-01T10:00:00Z
                      email_constraint: jane.doe@acme.example
                      enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                      expires_at: 2026-05-02T10:00:00Z
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      status: accepted
                      updated_at: 2026-05-01T10:00:00Z
                    session_expires_at: 2026-05-01T11:00:00Z
                    session_token: sess_eyJhbGciOiJSUzI1NiJ9.payload.sig
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_invitations.accept
  /user-invitations/cancel:
    post:
      description: Cancels a pending invitation. Requires `If-Match` for optimistic
        concurrency. Send `invitation_id` and optional `reason` in the body. Use
        the individual invitation GET response `ETag` header for `If-Match`; the
        body `etag` is the raw storage version. The list response header is an
        aggregate tag and cannot cancel an individual invitation.
      summary: Cancel user invitation
      tags:
        - Setup
        - User Invitations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              invitation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              reason: User withdrew their request
            schema:
              required:
                - invitation_id
              type: object
              additionalProperties: false
              properties:
                invitation_id:
                  type: string
                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                  format: uuid
                reason:
                  anyOf:
                    - type: string
                      maxLength: 500
                    - type: "null"
              examples:
                - invitation_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  reason: User withdrew their request
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                accepted_at: null
                cancelled_at: 2026-05-01T10:00:00Z
                created_at: 2026-05-01T10:00:00Z
                email_constraint: jane.doe@acme.example
                enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                expires_at: 2026-05-02T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: cancelled
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - status
                  - enterprise_ref
                  - scope
                  - email_constraint
                  - role
                  - pending_human_actor_ref
                  - invited_by
                  - expires_at
                  - accepted_at
                  - cancelled_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  cancelled_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  email_constraint:
                    type: string
                    pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                    maxLength: 254
                    format: email
                  enterprise_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  etag:
                    type: string
                    minLength: 1
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  invited_by:
                    type: string
                    pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  pending_human_actor_ref:
                    type: string
                    pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  role:
                    type: string
                    pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  scope:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - pending
                      - accepting
                      - accepted
                      - expired
                      - cancelled
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - accepted_at: null
                    cancelled_at: 2026-05-01T10:00:00Z
                    created_at: 2026-05-01T10:00:00Z
                    email_constraint: jane.doe@acme.example
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    expires_at: 2026-05-02T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: cancelled
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_invitations.cancel
      x-required-capability:
        - users.invite
  /user-invitations/resend:
    post:
      description: Resends first access for the invitation identified by the invited
        user (`user_ref`). Hosted invitations receive a refreshed magic-link
        email; an enterprise_idp invitation triggers its identity command
        instead and carries no hosted challenge. The role and scope remain
        unchanged.
      summary: Resend user invitation
      tags:
        - Setup
        - User Invitations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              user_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - user_ref
              type: object
              additionalProperties: false
              properties:
                user_ref:
                  type: string
                  pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - user_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                accepted_at: null
                cancelled_at: null
                created_at: 2026-05-01T10:00:00Z
                email_constraint: jane.doe@acme.example
                enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                expires_at: 2026-05-02T10:00:00Z
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: pending
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - status
                  - enterprise_ref
                  - scope
                  - email_constraint
                  - role
                  - pending_human_actor_ref
                  - invited_by
                  - expires_at
                  - accepted_at
                  - cancelled_at
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  accepted_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  cancelled_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  email_constraint:
                    type: string
                    pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                    maxLength: 254
                    format: email
                  enterprise_ref:
                    type: string
                    pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  etag:
                    type: string
                    minLength: 1
                  expires_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  invited_by:
                    type: string
                    pattern: ^(users|service-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  pending_human_actor_ref:
                    type: string
                    pattern: ^(users)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  role:
                    type: string
                    pattern: ^(roles)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  scope:
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - pending
                      - accepting
                      - accepted
                      - expired
                      - cancelled
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - accepted_at: null
                    cancelled_at: null
                    created_at: 2026-05-01T10:00:00Z
                    email_constraint: jane.doe@acme.example
                    enterprise_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    expires_at: 2026-05-02T10:00:00Z
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    invited_by: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    pending_human_actor_ref: users/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    role: roles/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    scope: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: pending
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: user_invitations.resend
      x-required-capability:
        - users.invite
  /users:
    get:
      description: Lists users directly under `scope_ref`. With
        `include_descendants=true`, `scope_ref` must identify an enterprise and
        the response includes users of that enterprise and its clients in one
        page sequence. Subtree mode requires `users.read` over the subtree and
        does not apply the `status` or `identity_source` filters; those filters
        apply only to the direct-scope listing.
      summary: List users
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: true
          schema:
            type: string
            pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - suspended
                  - deactivated
                  - pending_activation
                  - invited
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - suspended
                    - deactivated
                    - pending_activation
                    - invited
        - name: identity_source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - platform-managed
                  - federated
              - type: array
                items:
                  type: string
                  enum:
                    - platform-managed
                    - federated
        - name: include_descendants
          in: query
          required: false
          schema:
            type: string
            enum:
              - "true"
              - "false"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - status
                        - scope_ref
                        - identity_source
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        access_resend_event_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        display_name:
                          anyOf:
                            - type: string
                            - type: "null"
                        email:
                          anyOf:
                            - type: string
                              pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                              format: email
                            - type: "null"
                        email_changed_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        etag:
                          type: string
                          minLength: 1
                        federation:
                          anyOf:
                            - required:
                                - issuer
                                - external_subject
                              type: object
                              additionalProperties: false
                              properties:
                                external_subject:
                                  type: string
                                  minLength: 1
                                issuer:
                                  type: string
                                  minLength: 1
                            - type: "null"
                        federation_conflict:
                          anyOf:
                            - type: string
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        identity_source:
                          type: string
                          enum:
                            - platform-managed
                            - federated
                            - system
                        last_suspended_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        previous_email:
                          anyOf:
                            - type: string
                              pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                              format: email
                            - type: "null"
                        recovered_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        recovery_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        recovery_request:
                          anyOf:
                            - required:
                                - request_id
                                - approval_id
                                - state
                                - reason
                                - new_email
                                - created_at
                              type: object
                              additionalProperties: false
                              properties:
                                approval_id:
                                  anyOf:
                                    - type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    - type: "null"
                                created_at:
                                  type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                new_email:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                      format: email
                                    - type: "null"
                                reason:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                request_id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                state:
                                  type: string
                                  enum:
                                    - awaiting
                                    - executed
                                    - completed
                                    - failed
                                    - rejected
                                    - expired
                                    - cancelled
                                    - aborted
                                    - superseded
                            - type: "null"
                        recovery_requested_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: "null"
                        resource:
                          type: string
                          const: human_actor
                        scope_ref:
                          type: string
                          pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - suspended
                            - deactivated
                            - pending_activation
                            - invited
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - created_at: 2026-05-01T10:00:00Z
                        display_name: Jane Doe
                        email: jane.doe@acme.example
                        etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                        federation: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        identity_source: platform-managed
                        resource: human_actor
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00.000Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.list
      x-required-capability:
        - users.read
    post:
      summary: Create user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              display_name: Jane Doe
              email: jane.doe@acme.example
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              required:
                - scope_ref
                - email
              type: object
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                email:
                  type: string
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  format: email
                scope_ref:
                  type: string
                  pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              examples:
                - display_name: Jane Doe
                  email: jane.doe@acme.example
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.create
      x-required-capability:
        - users.create
  /users/{user_id}:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.get
      x-required-capability:
        - users.read
    patch:
      description: Patch a user. Requires `If-Match`.
      summary: Update user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            example:
              display_name: Jane Doe Updated
              email: jane.new@acme.example
            schema:
              type: object
              additionalProperties: false
              properties:
                display_name:
                  anyOf:
                    - type: string
                    - type: "null"
                email:
                  anyOf:
                    - type: string
                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                      format: email
                    - type: "null"
              examples:
                - display_name: Jane Doe Updated
                  email: jane.new@acme.example
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.update
      x-required-capability:
        - users.manage
  /users/{user_id}/access-resend:
    post:
      description: Emits the recovery command again for a user in `pending_activation`
        with a `recovery_id`. Requires `users.recovery_initiate`; one per user
        per five minutes (`429 resend_rate_limited`).
      summary: Re-send access to a recovering user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              schema:
                required:
                  - event_id
                type: object
                additionalProperties: false
                properties:
                  event_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.access_resend
      x-required-capability:
        - users.recovery_initiate
  /users/{user_id}/activate-federated:
    post:
      description: Called by an enterprise’s own identity backend (service principal,
        `private_key_jwt`) once the user finished first access or a recovery.
        The caller’s IdP row is taken from its verified token; `recovery_id` is
        forwarded unchanged.
      summary: Activate a user and bind their federated identity
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - issuer_uri
                - external_subject
              type: object
              additionalProperties: false
              properties:
                external_subject:
                  type: string
                  minLength: 1
                issuer_uri:
                  type: string
                  format: uri
                recovery_id:
                  anyOf:
                    - type: string
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      format: uuid
                    - type: "null"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              schema:
                required:
                  - human_actor_id
                  - invitation_id
                type: object
                additionalProperties: false
                properties:
                  human_actor_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  invitation_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.activate_federated
      x-required-capability:
        - users.activate_federated
  /users/{user_id}/deactivate:
    post:
      summary: Deactivate user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: deactivated
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: deactivated
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.deactivate
      x-required-capability:
        - users.manage
  /users/{user_id}/federation-binding:
    post:
      description: "Binds the user to the supplied issuer and external subject and
        returns the updated user. This route is closed for users of an
        enterprise whose first-access method is `enterprise_idp`: use `POST
        /users/{user_id}/activate-federated` for that path. Such requests return
        `409 state_conflict` with `data.reason =
        route_closed_for_enterprise_idp`."
      summary: Bind a user to a federated identity
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              external_subject: acme-user-123
              issuer_uri: https://identity.acme.example
            schema:
              required:
                - issuer_uri
                - external_subject
              type: object
              additionalProperties: false
              properties:
                external_subject:
                  type: string
                  minLength: 1
                issuer_uri:
                  type: string
                  format: uri
              examples:
                - external_subject: acme-user-123
                  issuer_uri: https://identity.acme.example
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation:
                  external_subject: acme-user-123
                  issuer: https://identity.acme.example
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: federated
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation:
                      external_subject: acme-user-123
                      issuer: https://identity.acme.example
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: federated
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.federation_binding
      x-required-capability:
        - users.manage
  /users/{user_id}/federation-conflict:
    parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      description: Clears a resolved conflict. Requires a platform-operator binding
        and `users.manage` on an `enterprise_wildcard` grant anchored at
        `platform-operators/<id>`.
      summary: Clear a federation conflict
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.federation_conflict.delete
      x-required-capability:
        - users.manage
    post:
      description: The enterprise identity backend reports an identity it will not
        overwrite. Shown on the enterprise card; only platform staff clear it.
      summary: Report a federation conflict
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - reason
              type: object
              additionalProperties: false
              properties:
                code:
                  anyOf:
                    - type: string
                      maxLength: 128
                    - type: "null"
                reason:
                  type: string
                  enum:
                    - email_taken_by_other_actor
                    - email_taken_by_unbound_identity
                    - activation_refused
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.federation_conflict
      x-required-capability:
        - users.activate_federated
  /users/{user_id}/hosted-access:
    post:
      description: Provisions hosted sign-in access for an existing user parented to a
        platform operator. The user must have an email address; the workspace is
        derived from the stored user and is not a request field. Send no request
        body. Available on development and sandbox deployments; production
        returns `409 state_conflict` with `data.reason = not_supported` because
        staff use corporate SSO there.
      summary: Grant hosted sign-in access to platform staff
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                subject_id: hosted-staff-123
              schema:
                required:
                  - subject_id
                type: object
                additionalProperties: false
                properties:
                  subject_id:
                    type: string
                    minLength: 1
                examples:
                  - subject_id: hosted-staff-123
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.hosted_access
      x-required-capability:
        - users.manage
  /users/{user_id}/reactivate:
    post:
      summary: Reactivate user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.reactivate
      x-required-capability:
        - users.manage
  /users/{user_id}/recovery:
    post:
      description: Platform support, after verifying the person out of band, opens an
        `identity.recovery` request; a compliance member approves it. Requires
        `users.recovery_initiate`. `expected_email` is the address support
        verified; `409 recovery_email_changed` when the user’s email is no
        longer that one. `400 recovery_verification_required` without
        `verification_ref`; `409 recovery_not_applicable`,
        `recovery_already_pending`, `recovery_new_email_taken`.
      summary: Open an access recovery
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - verification_method
                - expected_email
              type: object
              additionalProperties: false
              properties:
                expected_email:
                  type: string
                  pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  format: email
                new_email:
                  anyOf:
                    - type: string
                      pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                      format: email
                    - type: "null"
                verification_method:
                  type: string
                  enum:
                    - video_call
                    - kyb_representative
                    - document_check
                    - other
                verification_ref:
                  type: string
                  minLength: 1
                  maxLength: 512
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              schema:
                required:
                  - request_id
                  - approval_ref
                  - recovery_id
                type: object
                additionalProperties: false
                properties:
                  approval_ref:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  request_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.recovery
      x-required-capability:
        - users.recovery_initiate
  /users/{user_id}/recovery-request:
    post:
      description: "The enterprise asks the platform to recover a user’s access.
        Changes nothing else and creates no approval. On an enterprise that runs
        its own identity stack only an enterprise-bound caller may: platform
        staff get `403 platform_cannot_manage_federated_actor`."
      summary: Flag a user for access recovery
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              schema:
                required:
                  - recovery_requested_at
                type: object
                additionalProperties: false
                properties:
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.recovery_request
      x-required-capability:
        - users.manage
  /users/{user_id}/suspend:
    post:
      summary: Suspend user
      tags:
        - Setup
        - Users
      security:
        - BearerAuth: []
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  anyOf:
                    - type: string
                    - type: "null"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                display_name: Jane Doe
                email: jane.doe@acme.example
                etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                federation: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                identity_source: platform-managed
                last_suspended_at: 2026-05-01T10:00:00Z
                resource: human_actor
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: suspended
                updated_at: 2026-05-01T10:00:00.000Z
              schema:
                required:
                  - id
                  - resource
                  - status
                  - scope_ref
                  - identity_source
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  access_resend_event_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  display_name:
                    anyOf:
                      - type: string
                      - type: "null"
                  email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  email_changed_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  etag:
                    type: string
                    minLength: 1
                  federation:
                    anyOf:
                      - required:
                          - issuer
                          - external_subject
                        type: object
                        additionalProperties: false
                        properties:
                          external_subject:
                            type: string
                            minLength: 1
                          issuer:
                            type: string
                            minLength: 1
                      - type: "null"
                  federation_conflict:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  identity_source:
                    type: string
                    enum:
                      - platform-managed
                      - federated
                      - system
                  last_suspended_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  previous_email:
                    anyOf:
                      - type: string
                        pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                        format: email
                      - type: "null"
                  recovered_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  recovery_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  recovery_request:
                    anyOf:
                      - required:
                          - request_id
                          - approval_id
                          - state
                          - reason
                          - new_email
                          - created_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            anyOf:
                              - type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              - type: "null"
                          created_at:
                            type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          new_email:
                            anyOf:
                              - type: string
                                pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                                format: email
                              - type: "null"
                          reason:
                            anyOf:
                              - type: string
                              - type: "null"
                          request_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          state:
                            type: string
                            enum:
                              - awaiting
                              - executed
                              - completed
                              - failed
                              - rejected
                              - expired
                              - cancelled
                              - aborted
                              - superseded
                      - type: "null"
                  recovery_requested_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: human_actor
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|clients|platform-operators)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - suspended
                      - deactivated
                      - pending_activation
                      - invited
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    display_name: Jane Doe
                    email: jane.doe@acme.example
                    etag: 00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3
                    federation: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    identity_source: platform-managed
                    last_suspended_at: 2026-05-01T10:00:00Z
                    resource: human_actor
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: suspended
                    updated_at: 2026-05-01T10:00:00.000Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: users.suspend
      x-required-capability:
        - users.manage
  /webhook-subscriptions:
    get:
      description: Lists webhook subscriptions. If omitted, `scope_ref` is derived
        from the authenticated enterprise or client context.
      summary: List webhook subscriptions
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: scope_ref
          in: query
          required: false
          schema:
            description: Webhook subscriptions can be scoped only to an enterprise or
              client.
            anyOf:
              - type: string
                pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
              - type: string
                pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - active
                  - paused
                  - deleted
              - type: array
                items:
                  type: string
                  enum:
                    - active
                    - paused
                    - deleted
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - scope_ref
                        - url
                        - event_types
                        - status
                        - kind
                        - signing
                        - managed_by
                        - created_at
                        - updated_at
                        - etag
                      type: object
                      additionalProperties: false
                      properties:
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        etag:
                          type: string
                          minLength: 1
                        event_types:
                          type: array
                          items:
                            type: string
                            enum:
                              - "*"
                              - tenant.enterprise.admission_reviewed.v1
                              - tenant.enterprise.admitted.v1
                              - tenant.enterprise.activated.v1
                              - tenant.enterprise.updated.v1
                              - tenant.enterprise.suspended.v1
                              - tenant.enterprise.reactivated.v1
                              - tenant.enterprise.closed.v1
                              - tenant.enterprise.terminated.v1
                              - tenant.platform_operator.admitted.v1
                              - tenant.platform_operator.restricted.v1
                              - tenant.platform_operator.reactivated.v1
                              - tenant.platform_operator.offboarded.v1
                              - tenant.platform_operator.catalog_updated.v1
                              - tenant.master_account.created.v1
                              - tenant.master_account.suspended.v1
                              - tenant.master_account.closed.v1
                              - tenant.client.created.v1
                              - tenant.client.updated.v1
                              - tenant.client.suspended.v1
                              - tenant.client.reactivated.v1
                              - tenant.client.closed.v1
                              - tenant.client_account.created.v1
                              - tenant.client_account.suspended.v1
                              - tenant.client_account.reactivated.v1
                              - tenant.client_account.closed.v1
                              - ledger.transaction.posted.v1
                              - operations.withdrawal.requested.v1
                              - operations.withdrawal.admissible.v1
                              - operations.withdrawal.executing.v1
                              - operations.withdrawal.pending_approval.v1
                              - operations.withdrawal.pending_compliance.v1
                              - operations.withdrawal.approved.v1
                              - operations.withdrawal.settled.v1
                              - operations.withdrawal.failed.v1
                              - operations.withdrawal.cancelled.v1
                              - operations.conversion.requested.v1
                              - operations.conversion.admissible.v1
                              - operations.conversion.pending_approval.v1
                              - operations.conversion.pending_compliance.v1
                              - operations.conversion.approved.v1
                              - operations.conversion.settled.v1
                              - operations.conversion.failed.v1
                              - operations.conversion.cancelled.v1
                              - operations.external_settlement_conversion.pending_compliance.v1
                              - operations.internal_transfer.requested.v1
                              - operations.internal_transfer.admissible.v1
                              - operations.internal_transfer.pending_approval.v1
                              - operations.internal_transfer.pending_compliance.v1
                              - operations.internal_transfer.approved.v1
                              - operations.internal_transfer.settled.v1
                              - operations.internal_transfer.failed.v1
                              - operations.internal_transfer.cancelled.v1
                              - operations.on_ramp.requested.v1
                              - operations.on_ramp.admissible.v1
                              - operations.on_ramp.pending_approval.v1
                              - operations.on_ramp.pending_compliance.v1
                              - operations.on_ramp.approved.v1
                              - operations.on_ramp.settled.v1
                              - operations.on_ramp.failed.v1
                              - operations.on_ramp.cancelled.v1
                              - operations.off_ramp.requested.v1
                              - operations.off_ramp.admissible.v1
                              - operations.off_ramp.pending_approval.v1
                              - operations.off_ramp.pending_compliance.v1
                              - operations.off_ramp.approved.v1
                              - operations.off_ramp.settled.v1
                              - operations.off_ramp.failed.v1
                              - operations.off_ramp.cancelled.v1
                              - operations.deposit.requested.v1
                              - operations.deposit.admissible.v1
                              - operations.deposit.pending_approval.v1
                              - operations.deposit.pending_admission.v1
                              - operations.deposit.pending_compliance.v1
                              - operations.deposit.approved.v1
                              - operations.deposit.settled.v1
                              - operations.deposit.failed.v1
                              - operations.deposit.cancelled.v1
                              - rails.deposit.detected.v1
                              - rails.dispatch.acknowledged.v1
                              - rails.dispatch.rejected.v1
                              - rails.settlement.confirmed.v1
                              - kyc.verification.reviewed.v1
                              - loan.originated.v1
                              - loan.origination_failed.v1
                              - loan.margin_called.v1
                              - loan.margin_call_cleared.v1
                              - loan.liquidation_halted.v1
                              - loan.liquidated.v1
                              - loan.repaid.v1
                              - loan.extended.v1
                              - loan.closed.v1
                              - loan.force_closed.v1
                              - loan.reconciliation_discrepancy.v1
                              - tenant.enterprise.*.v1
                              - tenant.*.v1
                              - tenant.platform_operator.*.v1
                              - tenant.master_account.*.v1
                              - tenant.client.*.v1
                              - tenant.client_account.*.v1
                              - ledger.transaction.*.v1
                              - ledger.*.v1
                              - operations.withdrawal.*.v1
                              - operations.*.v1
                              - operations.conversion.*.v1
                              - operations.external_settlement_conversion.*.v1
                              - operations.internal_transfer.*.v1
                              - operations.on_ramp.*.v1
                              - operations.off_ramp.*.v1
                              - operations.deposit.*.v1
                              - rails.deposit.*.v1
                              - rails.*.v1
                              - rails.dispatch.*.v1
                              - rails.settlement.*.v1
                              - kyc.verification.*.v1
                              - kyc.*.v1
                              - loan.loan.*.v1
                              - loan.*.v1
                              - identity.human_actor.created.v1
                              - identity.human_actor.pending_created.v1
                              - identity.human_actor.activated.v1
                              - identity.human_actor.suspended.v1
                              - identity.human_actor.reactivated.v1
                              - identity.human_actor.deactivated.v1
                              - identity.human_actor.updated.v1
                              - identity.human_actor.federation_bound.v1
                              - identity.human_actor.*.v1
                              - identity.human_actor.access_resend_requested.v1
                              - identity.human_actor.recovery_requested.v1
                          minItems: 1
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        kind:
                          description: "Which catalog classes the subscription admits: public → public
                            events; identity → public and identity events;
                            command → command events only."
                          type: string
                          enum:
                            - public
                            - identity
                            - command
                        managed_by:
                          description: identity_provider_id of the IdP row that owns a core-managed
                            subscription; null for tenant-created ones.
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        resource:
                          type: string
                          const: webhook_subscription
                        scope_ref:
                          description: Webhook subscriptions can be scoped only to an enterprise or
                            client.
                          anyOf:
                            - type: string
                              pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: string
                              pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        signing:
                          description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                            only, verified against the published JWKS."
                          type: string
                          enum:
                            - hmac
                            - asymmetric
                        status:
                          type: string
                          enum:
                            - active
                            - paused
                            - deleted
                        updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        url:
                          type: string
                          format: uri
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - created_at: 2026-05-01T10:00:00Z
                        etag: 2026-05-01T10:00:00Z
                        event_types:
                          - operations.withdrawal.settled.v1
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: public
                        managed_by: null
                        resource: webhook_subscription
                        scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        signing: hmac
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                        url: https://example.com/webhooks
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.list
      x-required-capability:
        - webhooks.read
    post:
      description: Creates an active webhook subscription. If omitted, `scope_ref` is
        derived from the authenticated enterprise or client context; absence of
        both returns 400. Only enterprise and client subscription scopes are
        accepted. Use a public HTTPS callback URL and a non-empty signing
        secret. Public catalog event types and documented group wildcards are
        accepted; command types are refused with `event_type_not_subscribable`.
        Identity event filters additionally require users.read covering the
        whole subscription scope.
      summary: Create webhook subscription
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              event_types:
                - operations.withdrawal.settled.v1
              scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              secret: wh_secret_placeholder
              url: https://example.com/webhooks
            schema:
              required:
                - url
                - event_types
                - secret
              type: object
              additionalProperties: false
              properties:
                event_types:
                  description: Non-empty event type filter. Use ["*"] to subscribe to all event
                    types; otherwise provide exact catalog event types or
                    catalog-derived group wildcards such as
                    "operations.withdrawal.*.v1" and "operations.*.v1".
                  type: array
                  items:
                    description: Webhook event type filter value. Use exact catalog event types, "*"
                      for every event, "<domain>.<resource>.*.v<major>" for a
                      resource group, or "<domain>.*.v<major>" for a domain
                      group.
                    type: string
                    enum:
                      - "*"
                      - tenant.enterprise.admission_reviewed.v1
                      - tenant.enterprise.admitted.v1
                      - tenant.enterprise.activated.v1
                      - tenant.enterprise.updated.v1
                      - tenant.enterprise.suspended.v1
                      - tenant.enterprise.reactivated.v1
                      - tenant.enterprise.closed.v1
                      - tenant.enterprise.terminated.v1
                      - tenant.platform_operator.admitted.v1
                      - tenant.platform_operator.restricted.v1
                      - tenant.platform_operator.reactivated.v1
                      - tenant.platform_operator.offboarded.v1
                      - tenant.platform_operator.catalog_updated.v1
                      - tenant.master_account.created.v1
                      - tenant.master_account.suspended.v1
                      - tenant.master_account.closed.v1
                      - tenant.client.created.v1
                      - tenant.client.updated.v1
                      - tenant.client.suspended.v1
                      - tenant.client.reactivated.v1
                      - tenant.client.closed.v1
                      - tenant.client_account.created.v1
                      - tenant.client_account.suspended.v1
                      - tenant.client_account.reactivated.v1
                      - tenant.client_account.closed.v1
                      - ledger.transaction.posted.v1
                      - operations.withdrawal.requested.v1
                      - operations.withdrawal.admissible.v1
                      - operations.withdrawal.executing.v1
                      - operations.withdrawal.pending_approval.v1
                      - operations.withdrawal.pending_compliance.v1
                      - operations.withdrawal.approved.v1
                      - operations.withdrawal.settled.v1
                      - operations.withdrawal.failed.v1
                      - operations.withdrawal.cancelled.v1
                      - operations.conversion.requested.v1
                      - operations.conversion.admissible.v1
                      - operations.conversion.pending_approval.v1
                      - operations.conversion.pending_compliance.v1
                      - operations.conversion.approved.v1
                      - operations.conversion.settled.v1
                      - operations.conversion.failed.v1
                      - operations.conversion.cancelled.v1
                      - operations.external_settlement_conversion.pending_compliance.v1
                      - operations.internal_transfer.requested.v1
                      - operations.internal_transfer.admissible.v1
                      - operations.internal_transfer.pending_approval.v1
                      - operations.internal_transfer.pending_compliance.v1
                      - operations.internal_transfer.approved.v1
                      - operations.internal_transfer.settled.v1
                      - operations.internal_transfer.failed.v1
                      - operations.internal_transfer.cancelled.v1
                      - operations.on_ramp.requested.v1
                      - operations.on_ramp.admissible.v1
                      - operations.on_ramp.pending_approval.v1
                      - operations.on_ramp.pending_compliance.v1
                      - operations.on_ramp.approved.v1
                      - operations.on_ramp.settled.v1
                      - operations.on_ramp.failed.v1
                      - operations.on_ramp.cancelled.v1
                      - operations.off_ramp.requested.v1
                      - operations.off_ramp.admissible.v1
                      - operations.off_ramp.pending_approval.v1
                      - operations.off_ramp.pending_compliance.v1
                      - operations.off_ramp.approved.v1
                      - operations.off_ramp.settled.v1
                      - operations.off_ramp.failed.v1
                      - operations.off_ramp.cancelled.v1
                      - operations.deposit.requested.v1
                      - operations.deposit.admissible.v1
                      - operations.deposit.pending_approval.v1
                      - operations.deposit.pending_admission.v1
                      - operations.deposit.pending_compliance.v1
                      - operations.deposit.approved.v1
                      - operations.deposit.settled.v1
                      - operations.deposit.failed.v1
                      - operations.deposit.cancelled.v1
                      - rails.deposit.detected.v1
                      - rails.dispatch.acknowledged.v1
                      - rails.dispatch.rejected.v1
                      - rails.settlement.confirmed.v1
                      - kyc.verification.reviewed.v1
                      - loan.originated.v1
                      - loan.origination_failed.v1
                      - loan.margin_called.v1
                      - loan.margin_call_cleared.v1
                      - loan.liquidation_halted.v1
                      - loan.liquidated.v1
                      - loan.repaid.v1
                      - loan.extended.v1
                      - loan.closed.v1
                      - loan.force_closed.v1
                      - loan.reconciliation_discrepancy.v1
                      - tenant.enterprise.*.v1
                      - tenant.*.v1
                      - tenant.platform_operator.*.v1
                      - tenant.master_account.*.v1
                      - tenant.client.*.v1
                      - tenant.client_account.*.v1
                      - ledger.transaction.*.v1
                      - ledger.*.v1
                      - operations.withdrawal.*.v1
                      - operations.*.v1
                      - operations.conversion.*.v1
                      - operations.external_settlement_conversion.*.v1
                      - operations.internal_transfer.*.v1
                      - operations.on_ramp.*.v1
                      - operations.off_ramp.*.v1
                      - operations.deposit.*.v1
                      - rails.deposit.*.v1
                      - rails.*.v1
                      - rails.dispatch.*.v1
                      - rails.settlement.*.v1
                      - kyc.verification.*.v1
                      - kyc.*.v1
                      - loan.loan.*.v1
                      - loan.*.v1
                      - identity.human_actor.created.v1
                      - identity.human_actor.pending_created.v1
                      - identity.human_actor.activated.v1
                      - identity.human_actor.suspended.v1
                      - identity.human_actor.reactivated.v1
                      - identity.human_actor.deactivated.v1
                      - identity.human_actor.updated.v1
                      - identity.human_actor.federation_bound.v1
                      - identity.human_actor.*.v1
                  minItems: 1
                scope_ref:
                  description: Webhook subscriptions can be scoped only to an enterprise or
                    client.
                  anyOf:
                    - type: string
                      pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    - type: string
                      pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                secret:
                  type: string
                  minLength: 1
                url:
                  description: HTTPS callback URL on a public host. Plain http, private and
                    internal addresses are refused with
                    callback_url_not_allowed.
                  type: string
                  format: uri
              examples:
                - event_types:
                    - operations.withdrawal.settled.v1
                  scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  secret: wh_secret_placeholder
                  url: https://example.com/webhooks
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 2026-05-01T10:00:00Z
                event_types:
                  - operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kind: public
                managed_by: null
                resource: webhook_subscription
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                signing: hmac
                status: active
                updated_at: 2026-05-01T10:00:00Z
                url: https://example.com/webhooks
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - url
                  - event_types
                  - status
                  - kind
                  - signing
                  - managed_by
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  etag:
                    type: string
                    minLength: 1
                  event_types:
                    type: array
                    items:
                      type: string
                      enum:
                        - "*"
                        - tenant.enterprise.admission_reviewed.v1
                        - tenant.enterprise.admitted.v1
                        - tenant.enterprise.activated.v1
                        - tenant.enterprise.updated.v1
                        - tenant.enterprise.suspended.v1
                        - tenant.enterprise.reactivated.v1
                        - tenant.enterprise.closed.v1
                        - tenant.enterprise.terminated.v1
                        - tenant.platform_operator.admitted.v1
                        - tenant.platform_operator.restricted.v1
                        - tenant.platform_operator.reactivated.v1
                        - tenant.platform_operator.offboarded.v1
                        - tenant.platform_operator.catalog_updated.v1
                        - tenant.master_account.created.v1
                        - tenant.master_account.suspended.v1
                        - tenant.master_account.closed.v1
                        - tenant.client.created.v1
                        - tenant.client.updated.v1
                        - tenant.client.suspended.v1
                        - tenant.client.reactivated.v1
                        - tenant.client.closed.v1
                        - tenant.client_account.created.v1
                        - tenant.client_account.suspended.v1
                        - tenant.client_account.reactivated.v1
                        - tenant.client_account.closed.v1
                        - ledger.transaction.posted.v1
                        - operations.withdrawal.requested.v1
                        - operations.withdrawal.admissible.v1
                        - operations.withdrawal.executing.v1
                        - operations.withdrawal.pending_approval.v1
                        - operations.withdrawal.pending_compliance.v1
                        - operations.withdrawal.approved.v1
                        - operations.withdrawal.settled.v1
                        - operations.withdrawal.failed.v1
                        - operations.withdrawal.cancelled.v1
                        - operations.conversion.requested.v1
                        - operations.conversion.admissible.v1
                        - operations.conversion.pending_approval.v1
                        - operations.conversion.pending_compliance.v1
                        - operations.conversion.approved.v1
                        - operations.conversion.settled.v1
                        - operations.conversion.failed.v1
                        - operations.conversion.cancelled.v1
                        - operations.external_settlement_conversion.pending_compliance.v1
                        - operations.internal_transfer.requested.v1
                        - operations.internal_transfer.admissible.v1
                        - operations.internal_transfer.pending_approval.v1
                        - operations.internal_transfer.pending_compliance.v1
                        - operations.internal_transfer.approved.v1
                        - operations.internal_transfer.settled.v1
                        - operations.internal_transfer.failed.v1
                        - operations.internal_transfer.cancelled.v1
                        - operations.on_ramp.requested.v1
                        - operations.on_ramp.admissible.v1
                        - operations.on_ramp.pending_approval.v1
                        - operations.on_ramp.pending_compliance.v1
                        - operations.on_ramp.approved.v1
                        - operations.on_ramp.settled.v1
                        - operations.on_ramp.failed.v1
                        - operations.on_ramp.cancelled.v1
                        - operations.off_ramp.requested.v1
                        - operations.off_ramp.admissible.v1
                        - operations.off_ramp.pending_approval.v1
                        - operations.off_ramp.pending_compliance.v1
                        - operations.off_ramp.approved.v1
                        - operations.off_ramp.settled.v1
                        - operations.off_ramp.failed.v1
                        - operations.off_ramp.cancelled.v1
                        - operations.deposit.requested.v1
                        - operations.deposit.admissible.v1
                        - operations.deposit.pending_approval.v1
                        - operations.deposit.pending_admission.v1
                        - operations.deposit.pending_compliance.v1
                        - operations.deposit.approved.v1
                        - operations.deposit.settled.v1
                        - operations.deposit.failed.v1
                        - operations.deposit.cancelled.v1
                        - rails.deposit.detected.v1
                        - rails.dispatch.acknowledged.v1
                        - rails.dispatch.rejected.v1
                        - rails.settlement.confirmed.v1
                        - kyc.verification.reviewed.v1
                        - loan.originated.v1
                        - loan.origination_failed.v1
                        - loan.margin_called.v1
                        - loan.margin_call_cleared.v1
                        - loan.liquidation_halted.v1
                        - loan.liquidated.v1
                        - loan.repaid.v1
                        - loan.extended.v1
                        - loan.closed.v1
                        - loan.force_closed.v1
                        - loan.reconciliation_discrepancy.v1
                        - tenant.enterprise.*.v1
                        - tenant.*.v1
                        - tenant.platform_operator.*.v1
                        - tenant.master_account.*.v1
                        - tenant.client.*.v1
                        - tenant.client_account.*.v1
                        - ledger.transaction.*.v1
                        - ledger.*.v1
                        - operations.withdrawal.*.v1
                        - operations.*.v1
                        - operations.conversion.*.v1
                        - operations.external_settlement_conversion.*.v1
                        - operations.internal_transfer.*.v1
                        - operations.on_ramp.*.v1
                        - operations.off_ramp.*.v1
                        - operations.deposit.*.v1
                        - rails.deposit.*.v1
                        - rails.*.v1
                        - rails.dispatch.*.v1
                        - rails.settlement.*.v1
                        - kyc.verification.*.v1
                        - kyc.*.v1
                        - loan.loan.*.v1
                        - loan.*.v1
                        - identity.human_actor.created.v1
                        - identity.human_actor.pending_created.v1
                        - identity.human_actor.activated.v1
                        - identity.human_actor.suspended.v1
                        - identity.human_actor.reactivated.v1
                        - identity.human_actor.deactivated.v1
                        - identity.human_actor.updated.v1
                        - identity.human_actor.federation_bound.v1
                        - identity.human_actor.*.v1
                        - identity.human_actor.access_resend_requested.v1
                        - identity.human_actor.recovery_requested.v1
                    minItems: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kind:
                    description: "Which catalog classes the subscription admits: public → public
                      events; identity → public and identity events; command →
                      command events only."
                    type: string
                    enum:
                      - public
                      - identity
                      - command
                  managed_by:
                    description: identity_provider_id of the IdP row that owns a core-managed
                      subscription; null for tenant-created ones.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_subscription
                  scope_ref:
                    description: Webhook subscriptions can be scoped only to an enterprise or
                      client.
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  signing:
                    description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                      only, verified against the published JWKS."
                    type: string
                    enum:
                      - hmac
                      - asymmetric
                  status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  url:
                    type: string
                    format: uri
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.create
      x-required-capability:
        - webhooks.create
  /webhook-subscriptions/{subscription_id}:
    parameters:
      - name: subscription_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      summary: Get webhook subscription
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 2026-05-01T10:00:00Z
                event_types:
                  - operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kind: public
                managed_by: null
                resource: webhook_subscription
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                signing: hmac
                status: active
                updated_at: 2026-05-01T10:00:00Z
                url: https://example.com/webhooks
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - url
                  - event_types
                  - status
                  - kind
                  - signing
                  - managed_by
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  etag:
                    type: string
                    minLength: 1
                  event_types:
                    type: array
                    items:
                      type: string
                      enum:
                        - "*"
                        - tenant.enterprise.admission_reviewed.v1
                        - tenant.enterprise.admitted.v1
                        - tenant.enterprise.activated.v1
                        - tenant.enterprise.updated.v1
                        - tenant.enterprise.suspended.v1
                        - tenant.enterprise.reactivated.v1
                        - tenant.enterprise.closed.v1
                        - tenant.enterprise.terminated.v1
                        - tenant.platform_operator.admitted.v1
                        - tenant.platform_operator.restricted.v1
                        - tenant.platform_operator.reactivated.v1
                        - tenant.platform_operator.offboarded.v1
                        - tenant.platform_operator.catalog_updated.v1
                        - tenant.master_account.created.v1
                        - tenant.master_account.suspended.v1
                        - tenant.master_account.closed.v1
                        - tenant.client.created.v1
                        - tenant.client.updated.v1
                        - tenant.client.suspended.v1
                        - tenant.client.reactivated.v1
                        - tenant.client.closed.v1
                        - tenant.client_account.created.v1
                        - tenant.client_account.suspended.v1
                        - tenant.client_account.reactivated.v1
                        - tenant.client_account.closed.v1
                        - ledger.transaction.posted.v1
                        - operations.withdrawal.requested.v1
                        - operations.withdrawal.admissible.v1
                        - operations.withdrawal.executing.v1
                        - operations.withdrawal.pending_approval.v1
                        - operations.withdrawal.pending_compliance.v1
                        - operations.withdrawal.approved.v1
                        - operations.withdrawal.settled.v1
                        - operations.withdrawal.failed.v1
                        - operations.withdrawal.cancelled.v1
                        - operations.conversion.requested.v1
                        - operations.conversion.admissible.v1
                        - operations.conversion.pending_approval.v1
                        - operations.conversion.pending_compliance.v1
                        - operations.conversion.approved.v1
                        - operations.conversion.settled.v1
                        - operations.conversion.failed.v1
                        - operations.conversion.cancelled.v1
                        - operations.external_settlement_conversion.pending_compliance.v1
                        - operations.internal_transfer.requested.v1
                        - operations.internal_transfer.admissible.v1
                        - operations.internal_transfer.pending_approval.v1
                        - operations.internal_transfer.pending_compliance.v1
                        - operations.internal_transfer.approved.v1
                        - operations.internal_transfer.settled.v1
                        - operations.internal_transfer.failed.v1
                        - operations.internal_transfer.cancelled.v1
                        - operations.on_ramp.requested.v1
                        - operations.on_ramp.admissible.v1
                        - operations.on_ramp.pending_approval.v1
                        - operations.on_ramp.pending_compliance.v1
                        - operations.on_ramp.approved.v1
                        - operations.on_ramp.settled.v1
                        - operations.on_ramp.failed.v1
                        - operations.on_ramp.cancelled.v1
                        - operations.off_ramp.requested.v1
                        - operations.off_ramp.admissible.v1
                        - operations.off_ramp.pending_approval.v1
                        - operations.off_ramp.pending_compliance.v1
                        - operations.off_ramp.approved.v1
                        - operations.off_ramp.settled.v1
                        - operations.off_ramp.failed.v1
                        - operations.off_ramp.cancelled.v1
                        - operations.deposit.requested.v1
                        - operations.deposit.admissible.v1
                        - operations.deposit.pending_approval.v1
                        - operations.deposit.pending_admission.v1
                        - operations.deposit.pending_compliance.v1
                        - operations.deposit.approved.v1
                        - operations.deposit.settled.v1
                        - operations.deposit.failed.v1
                        - operations.deposit.cancelled.v1
                        - rails.deposit.detected.v1
                        - rails.dispatch.acknowledged.v1
                        - rails.dispatch.rejected.v1
                        - rails.settlement.confirmed.v1
                        - kyc.verification.reviewed.v1
                        - loan.originated.v1
                        - loan.origination_failed.v1
                        - loan.margin_called.v1
                        - loan.margin_call_cleared.v1
                        - loan.liquidation_halted.v1
                        - loan.liquidated.v1
                        - loan.repaid.v1
                        - loan.extended.v1
                        - loan.closed.v1
                        - loan.force_closed.v1
                        - loan.reconciliation_discrepancy.v1
                        - tenant.enterprise.*.v1
                        - tenant.*.v1
                        - tenant.platform_operator.*.v1
                        - tenant.master_account.*.v1
                        - tenant.client.*.v1
                        - tenant.client_account.*.v1
                        - ledger.transaction.*.v1
                        - ledger.*.v1
                        - operations.withdrawal.*.v1
                        - operations.*.v1
                        - operations.conversion.*.v1
                        - operations.external_settlement_conversion.*.v1
                        - operations.internal_transfer.*.v1
                        - operations.on_ramp.*.v1
                        - operations.off_ramp.*.v1
                        - operations.deposit.*.v1
                        - rails.deposit.*.v1
                        - rails.*.v1
                        - rails.dispatch.*.v1
                        - rails.settlement.*.v1
                        - kyc.verification.*.v1
                        - kyc.*.v1
                        - loan.loan.*.v1
                        - loan.*.v1
                        - identity.human_actor.created.v1
                        - identity.human_actor.pending_created.v1
                        - identity.human_actor.activated.v1
                        - identity.human_actor.suspended.v1
                        - identity.human_actor.reactivated.v1
                        - identity.human_actor.deactivated.v1
                        - identity.human_actor.updated.v1
                        - identity.human_actor.federation_bound.v1
                        - identity.human_actor.*.v1
                        - identity.human_actor.access_resend_requested.v1
                        - identity.human_actor.recovery_requested.v1
                    minItems: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kind:
                    description: "Which catalog classes the subscription admits: public → public
                      events; identity → public and identity events; command →
                      command events only."
                    type: string
                    enum:
                      - public
                      - identity
                      - command
                  managed_by:
                    description: identity_provider_id of the IdP row that owns a core-managed
                      subscription; null for tenant-created ones.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_subscription
                  scope_ref:
                    description: Webhook subscriptions can be scoped only to an enterprise or
                      client.
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  signing:
                    description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                      only, verified against the published JWKS."
                    type: string
                    enum:
                      - hmac
                      - asymmetric
                  status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  url:
                    type: string
                    format: uri
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.get
      x-required-capability:
        - webhooks.read
    patch:
      description: Updates the supplied fields and requires the current If-Match
        entity tag from a prior resource read. Platform-managed subscriptions
        cannot be changed here. Deleted subscriptions cannot be updated or
        reactivated; attempts return 409 with reason
        `webhook_subscription_not_active`. Keeping or widening an identity event
        stream additionally requires users.read covering the subscription scope;
        pausing or deleting without other changes only narrows the stream.
      summary: Update webhook subscription
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            example:
              status: paused
              url: https://example.com/webhooks/updated
            schema:
              type: object
              additionalProperties: false
              properties:
                event_types:
                  description: Non-empty event type filter. Use ["*"] to subscribe to all event
                    types; otherwise provide exact catalog event types or
                    catalog-derived group wildcards such as
                    "operations.withdrawal.*.v1" and "operations.*.v1".
                  type: array
                  items:
                    description: Webhook event type filter value. Use exact catalog event types, "*"
                      for every event, "<domain>.<resource>.*.v<major>" for a
                      resource group, or "<domain>.*.v<major>" for a domain
                      group.
                    type: string
                    enum:
                      - "*"
                      - tenant.enterprise.admission_reviewed.v1
                      - tenant.enterprise.admitted.v1
                      - tenant.enterprise.activated.v1
                      - tenant.enterprise.updated.v1
                      - tenant.enterprise.suspended.v1
                      - tenant.enterprise.reactivated.v1
                      - tenant.enterprise.closed.v1
                      - tenant.enterprise.terminated.v1
                      - tenant.platform_operator.admitted.v1
                      - tenant.platform_operator.restricted.v1
                      - tenant.platform_operator.reactivated.v1
                      - tenant.platform_operator.offboarded.v1
                      - tenant.platform_operator.catalog_updated.v1
                      - tenant.master_account.created.v1
                      - tenant.master_account.suspended.v1
                      - tenant.master_account.closed.v1
                      - tenant.client.created.v1
                      - tenant.client.updated.v1
                      - tenant.client.suspended.v1
                      - tenant.client.reactivated.v1
                      - tenant.client.closed.v1
                      - tenant.client_account.created.v1
                      - tenant.client_account.suspended.v1
                      - tenant.client_account.reactivated.v1
                      - tenant.client_account.closed.v1
                      - ledger.transaction.posted.v1
                      - operations.withdrawal.requested.v1
                      - operations.withdrawal.admissible.v1
                      - operations.withdrawal.executing.v1
                      - operations.withdrawal.pending_approval.v1
                      - operations.withdrawal.pending_compliance.v1
                      - operations.withdrawal.approved.v1
                      - operations.withdrawal.settled.v1
                      - operations.withdrawal.failed.v1
                      - operations.withdrawal.cancelled.v1
                      - operations.conversion.requested.v1
                      - operations.conversion.admissible.v1
                      - operations.conversion.pending_approval.v1
                      - operations.conversion.pending_compliance.v1
                      - operations.conversion.approved.v1
                      - operations.conversion.settled.v1
                      - operations.conversion.failed.v1
                      - operations.conversion.cancelled.v1
                      - operations.external_settlement_conversion.pending_compliance.v1
                      - operations.internal_transfer.requested.v1
                      - operations.internal_transfer.admissible.v1
                      - operations.internal_transfer.pending_approval.v1
                      - operations.internal_transfer.pending_compliance.v1
                      - operations.internal_transfer.approved.v1
                      - operations.internal_transfer.settled.v1
                      - operations.internal_transfer.failed.v1
                      - operations.internal_transfer.cancelled.v1
                      - operations.on_ramp.requested.v1
                      - operations.on_ramp.admissible.v1
                      - operations.on_ramp.pending_approval.v1
                      - operations.on_ramp.pending_compliance.v1
                      - operations.on_ramp.approved.v1
                      - operations.on_ramp.settled.v1
                      - operations.on_ramp.failed.v1
                      - operations.on_ramp.cancelled.v1
                      - operations.off_ramp.requested.v1
                      - operations.off_ramp.admissible.v1
                      - operations.off_ramp.pending_approval.v1
                      - operations.off_ramp.pending_compliance.v1
                      - operations.off_ramp.approved.v1
                      - operations.off_ramp.settled.v1
                      - operations.off_ramp.failed.v1
                      - operations.off_ramp.cancelled.v1
                      - operations.deposit.requested.v1
                      - operations.deposit.admissible.v1
                      - operations.deposit.pending_approval.v1
                      - operations.deposit.pending_admission.v1
                      - operations.deposit.pending_compliance.v1
                      - operations.deposit.approved.v1
                      - operations.deposit.settled.v1
                      - operations.deposit.failed.v1
                      - operations.deposit.cancelled.v1
                      - rails.deposit.detected.v1
                      - rails.dispatch.acknowledged.v1
                      - rails.dispatch.rejected.v1
                      - rails.settlement.confirmed.v1
                      - kyc.verification.reviewed.v1
                      - loan.originated.v1
                      - loan.origination_failed.v1
                      - loan.margin_called.v1
                      - loan.margin_call_cleared.v1
                      - loan.liquidation_halted.v1
                      - loan.liquidated.v1
                      - loan.repaid.v1
                      - loan.extended.v1
                      - loan.closed.v1
                      - loan.force_closed.v1
                      - loan.reconciliation_discrepancy.v1
                      - tenant.enterprise.*.v1
                      - tenant.*.v1
                      - tenant.platform_operator.*.v1
                      - tenant.master_account.*.v1
                      - tenant.client.*.v1
                      - tenant.client_account.*.v1
                      - ledger.transaction.*.v1
                      - ledger.*.v1
                      - operations.withdrawal.*.v1
                      - operations.*.v1
                      - operations.conversion.*.v1
                      - operations.external_settlement_conversion.*.v1
                      - operations.internal_transfer.*.v1
                      - operations.on_ramp.*.v1
                      - operations.off_ramp.*.v1
                      - operations.deposit.*.v1
                      - rails.deposit.*.v1
                      - rails.*.v1
                      - rails.dispatch.*.v1
                      - rails.settlement.*.v1
                      - kyc.verification.*.v1
                      - kyc.*.v1
                      - loan.loan.*.v1
                      - loan.*.v1
                      - identity.human_actor.created.v1
                      - identity.human_actor.pending_created.v1
                      - identity.human_actor.activated.v1
                      - identity.human_actor.suspended.v1
                      - identity.human_actor.reactivated.v1
                      - identity.human_actor.deactivated.v1
                      - identity.human_actor.updated.v1
                      - identity.human_actor.federation_bound.v1
                      - identity.human_actor.*.v1
                  minItems: 1
                status:
                  type: string
                  enum:
                    - active
                    - paused
                    - deleted
                url:
                  description: HTTPS callback URL on a public host. Plain http, private and
                    internal addresses are refused with
                    callback_url_not_allowed.
                  type: string
                  format: uri
              examples:
                - status: paused
                  url: https://example.com/webhooks/updated
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 2026-05-01T10:00:00Z
                event_types:
                  - operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kind: public
                managed_by: null
                resource: webhook_subscription
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                signing: hmac
                status: paused
                updated_at: 2026-05-01T10:00:00Z
                url: https://example.com/webhooks/updated
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - url
                  - event_types
                  - status
                  - kind
                  - signing
                  - managed_by
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  etag:
                    type: string
                    minLength: 1
                  event_types:
                    type: array
                    items:
                      type: string
                      enum:
                        - "*"
                        - tenant.enterprise.admission_reviewed.v1
                        - tenant.enterprise.admitted.v1
                        - tenant.enterprise.activated.v1
                        - tenant.enterprise.updated.v1
                        - tenant.enterprise.suspended.v1
                        - tenant.enterprise.reactivated.v1
                        - tenant.enterprise.closed.v1
                        - tenant.enterprise.terminated.v1
                        - tenant.platform_operator.admitted.v1
                        - tenant.platform_operator.restricted.v1
                        - tenant.platform_operator.reactivated.v1
                        - tenant.platform_operator.offboarded.v1
                        - tenant.platform_operator.catalog_updated.v1
                        - tenant.master_account.created.v1
                        - tenant.master_account.suspended.v1
                        - tenant.master_account.closed.v1
                        - tenant.client.created.v1
                        - tenant.client.updated.v1
                        - tenant.client.suspended.v1
                        - tenant.client.reactivated.v1
                        - tenant.client.closed.v1
                        - tenant.client_account.created.v1
                        - tenant.client_account.suspended.v1
                        - tenant.client_account.reactivated.v1
                        - tenant.client_account.closed.v1
                        - ledger.transaction.posted.v1
                        - operations.withdrawal.requested.v1
                        - operations.withdrawal.admissible.v1
                        - operations.withdrawal.executing.v1
                        - operations.withdrawal.pending_approval.v1
                        - operations.withdrawal.pending_compliance.v1
                        - operations.withdrawal.approved.v1
                        - operations.withdrawal.settled.v1
                        - operations.withdrawal.failed.v1
                        - operations.withdrawal.cancelled.v1
                        - operations.conversion.requested.v1
                        - operations.conversion.admissible.v1
                        - operations.conversion.pending_approval.v1
                        - operations.conversion.pending_compliance.v1
                        - operations.conversion.approved.v1
                        - operations.conversion.settled.v1
                        - operations.conversion.failed.v1
                        - operations.conversion.cancelled.v1
                        - operations.external_settlement_conversion.pending_compliance.v1
                        - operations.internal_transfer.requested.v1
                        - operations.internal_transfer.admissible.v1
                        - operations.internal_transfer.pending_approval.v1
                        - operations.internal_transfer.pending_compliance.v1
                        - operations.internal_transfer.approved.v1
                        - operations.internal_transfer.settled.v1
                        - operations.internal_transfer.failed.v1
                        - operations.internal_transfer.cancelled.v1
                        - operations.on_ramp.requested.v1
                        - operations.on_ramp.admissible.v1
                        - operations.on_ramp.pending_approval.v1
                        - operations.on_ramp.pending_compliance.v1
                        - operations.on_ramp.approved.v1
                        - operations.on_ramp.settled.v1
                        - operations.on_ramp.failed.v1
                        - operations.on_ramp.cancelled.v1
                        - operations.off_ramp.requested.v1
                        - operations.off_ramp.admissible.v1
                        - operations.off_ramp.pending_approval.v1
                        - operations.off_ramp.pending_compliance.v1
                        - operations.off_ramp.approved.v1
                        - operations.off_ramp.settled.v1
                        - operations.off_ramp.failed.v1
                        - operations.off_ramp.cancelled.v1
                        - operations.deposit.requested.v1
                        - operations.deposit.admissible.v1
                        - operations.deposit.pending_approval.v1
                        - operations.deposit.pending_admission.v1
                        - operations.deposit.pending_compliance.v1
                        - operations.deposit.approved.v1
                        - operations.deposit.settled.v1
                        - operations.deposit.failed.v1
                        - operations.deposit.cancelled.v1
                        - rails.deposit.detected.v1
                        - rails.dispatch.acknowledged.v1
                        - rails.dispatch.rejected.v1
                        - rails.settlement.confirmed.v1
                        - kyc.verification.reviewed.v1
                        - loan.originated.v1
                        - loan.origination_failed.v1
                        - loan.margin_called.v1
                        - loan.margin_call_cleared.v1
                        - loan.liquidation_halted.v1
                        - loan.liquidated.v1
                        - loan.repaid.v1
                        - loan.extended.v1
                        - loan.closed.v1
                        - loan.force_closed.v1
                        - loan.reconciliation_discrepancy.v1
                        - tenant.enterprise.*.v1
                        - tenant.*.v1
                        - tenant.platform_operator.*.v1
                        - tenant.master_account.*.v1
                        - tenant.client.*.v1
                        - tenant.client_account.*.v1
                        - ledger.transaction.*.v1
                        - ledger.*.v1
                        - operations.withdrawal.*.v1
                        - operations.*.v1
                        - operations.conversion.*.v1
                        - operations.external_settlement_conversion.*.v1
                        - operations.internal_transfer.*.v1
                        - operations.on_ramp.*.v1
                        - operations.off_ramp.*.v1
                        - operations.deposit.*.v1
                        - rails.deposit.*.v1
                        - rails.*.v1
                        - rails.dispatch.*.v1
                        - rails.settlement.*.v1
                        - kyc.verification.*.v1
                        - kyc.*.v1
                        - loan.loan.*.v1
                        - loan.*.v1
                        - identity.human_actor.created.v1
                        - identity.human_actor.pending_created.v1
                        - identity.human_actor.activated.v1
                        - identity.human_actor.suspended.v1
                        - identity.human_actor.reactivated.v1
                        - identity.human_actor.deactivated.v1
                        - identity.human_actor.updated.v1
                        - identity.human_actor.federation_bound.v1
                        - identity.human_actor.*.v1
                        - identity.human_actor.access_resend_requested.v1
                        - identity.human_actor.recovery_requested.v1
                    minItems: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kind:
                    description: "Which catalog classes the subscription admits: public → public
                      events; identity → public and identity events; command →
                      command events only."
                    type: string
                    enum:
                      - public
                      - identity
                      - command
                  managed_by:
                    description: identity_provider_id of the IdP row that owns a core-managed
                      subscription; null for tenant-created ones.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_subscription
                  scope_ref:
                    description: Webhook subscriptions can be scoped only to an enterprise or
                      client.
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  signing:
                    description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                      only, verified against the published JWKS."
                    type: string
                    enum:
                      - hmac
                      - asymmetric
                  status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  url:
                    type: string
                    format: uri
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: paused
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks/updated
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.update
      x-required-capability:
        - webhooks.manage
  /webhook-subscriptions/{subscription_id}/delete:
    post:
      description: "Marks the subscription `deleted` and returns its resource
        snapshot. Deletion is terminal: later edits or lifecycle changes return
        409 with reason `webhook_subscription_not_active` when the supplied
        If-Match is current. Requires the current If-Match entity tag.
        Platform-managed subscriptions cannot be changed through this route."
      summary: Delete webhook subscription
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 2026-05-01T10:00:00Z
                event_types:
                  - operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kind: public
                managed_by: null
                resource: webhook_subscription
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                signing: hmac
                status: deleted
                updated_at: 2026-05-01T10:00:00Z
                url: https://example.com/webhooks
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - url
                  - event_types
                  - status
                  - kind
                  - signing
                  - managed_by
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  etag:
                    type: string
                    minLength: 1
                  event_types:
                    type: array
                    items:
                      type: string
                      enum:
                        - "*"
                        - tenant.enterprise.admission_reviewed.v1
                        - tenant.enterprise.admitted.v1
                        - tenant.enterprise.activated.v1
                        - tenant.enterprise.updated.v1
                        - tenant.enterprise.suspended.v1
                        - tenant.enterprise.reactivated.v1
                        - tenant.enterprise.closed.v1
                        - tenant.enterprise.terminated.v1
                        - tenant.platform_operator.admitted.v1
                        - tenant.platform_operator.restricted.v1
                        - tenant.platform_operator.reactivated.v1
                        - tenant.platform_operator.offboarded.v1
                        - tenant.platform_operator.catalog_updated.v1
                        - tenant.master_account.created.v1
                        - tenant.master_account.suspended.v1
                        - tenant.master_account.closed.v1
                        - tenant.client.created.v1
                        - tenant.client.updated.v1
                        - tenant.client.suspended.v1
                        - tenant.client.reactivated.v1
                        - tenant.client.closed.v1
                        - tenant.client_account.created.v1
                        - tenant.client_account.suspended.v1
                        - tenant.client_account.reactivated.v1
                        - tenant.client_account.closed.v1
                        - ledger.transaction.posted.v1
                        - operations.withdrawal.requested.v1
                        - operations.withdrawal.admissible.v1
                        - operations.withdrawal.executing.v1
                        - operations.withdrawal.pending_approval.v1
                        - operations.withdrawal.pending_compliance.v1
                        - operations.withdrawal.approved.v1
                        - operations.withdrawal.settled.v1
                        - operations.withdrawal.failed.v1
                        - operations.withdrawal.cancelled.v1
                        - operations.conversion.requested.v1
                        - operations.conversion.admissible.v1
                        - operations.conversion.pending_approval.v1
                        - operations.conversion.pending_compliance.v1
                        - operations.conversion.approved.v1
                        - operations.conversion.settled.v1
                        - operations.conversion.failed.v1
                        - operations.conversion.cancelled.v1
                        - operations.external_settlement_conversion.pending_compliance.v1
                        - operations.internal_transfer.requested.v1
                        - operations.internal_transfer.admissible.v1
                        - operations.internal_transfer.pending_approval.v1
                        - operations.internal_transfer.pending_compliance.v1
                        - operations.internal_transfer.approved.v1
                        - operations.internal_transfer.settled.v1
                        - operations.internal_transfer.failed.v1
                        - operations.internal_transfer.cancelled.v1
                        - operations.on_ramp.requested.v1
                        - operations.on_ramp.admissible.v1
                        - operations.on_ramp.pending_approval.v1
                        - operations.on_ramp.pending_compliance.v1
                        - operations.on_ramp.approved.v1
                        - operations.on_ramp.settled.v1
                        - operations.on_ramp.failed.v1
                        - operations.on_ramp.cancelled.v1
                        - operations.off_ramp.requested.v1
                        - operations.off_ramp.admissible.v1
                        - operations.off_ramp.pending_approval.v1
                        - operations.off_ramp.pending_compliance.v1
                        - operations.off_ramp.approved.v1
                        - operations.off_ramp.settled.v1
                        - operations.off_ramp.failed.v1
                        - operations.off_ramp.cancelled.v1
                        - operations.deposit.requested.v1
                        - operations.deposit.admissible.v1
                        - operations.deposit.pending_approval.v1
                        - operations.deposit.pending_admission.v1
                        - operations.deposit.pending_compliance.v1
                        - operations.deposit.approved.v1
                        - operations.deposit.settled.v1
                        - operations.deposit.failed.v1
                        - operations.deposit.cancelled.v1
                        - rails.deposit.detected.v1
                        - rails.dispatch.acknowledged.v1
                        - rails.dispatch.rejected.v1
                        - rails.settlement.confirmed.v1
                        - kyc.verification.reviewed.v1
                        - loan.originated.v1
                        - loan.origination_failed.v1
                        - loan.margin_called.v1
                        - loan.margin_call_cleared.v1
                        - loan.liquidation_halted.v1
                        - loan.liquidated.v1
                        - loan.repaid.v1
                        - loan.extended.v1
                        - loan.closed.v1
                        - loan.force_closed.v1
                        - loan.reconciliation_discrepancy.v1
                        - tenant.enterprise.*.v1
                        - tenant.*.v1
                        - tenant.platform_operator.*.v1
                        - tenant.master_account.*.v1
                        - tenant.client.*.v1
                        - tenant.client_account.*.v1
                        - ledger.transaction.*.v1
                        - ledger.*.v1
                        - operations.withdrawal.*.v1
                        - operations.*.v1
                        - operations.conversion.*.v1
                        - operations.external_settlement_conversion.*.v1
                        - operations.internal_transfer.*.v1
                        - operations.on_ramp.*.v1
                        - operations.off_ramp.*.v1
                        - operations.deposit.*.v1
                        - rails.deposit.*.v1
                        - rails.*.v1
                        - rails.dispatch.*.v1
                        - rails.settlement.*.v1
                        - kyc.verification.*.v1
                        - kyc.*.v1
                        - loan.loan.*.v1
                        - loan.*.v1
                        - identity.human_actor.created.v1
                        - identity.human_actor.pending_created.v1
                        - identity.human_actor.activated.v1
                        - identity.human_actor.suspended.v1
                        - identity.human_actor.reactivated.v1
                        - identity.human_actor.deactivated.v1
                        - identity.human_actor.updated.v1
                        - identity.human_actor.federation_bound.v1
                        - identity.human_actor.*.v1
                        - identity.human_actor.access_resend_requested.v1
                        - identity.human_actor.recovery_requested.v1
                    minItems: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kind:
                    description: "Which catalog classes the subscription admits: public → public
                      events; identity → public and identity events; command →
                      command events only."
                    type: string
                    enum:
                      - public
                      - identity
                      - command
                  managed_by:
                    description: identity_provider_id of the IdP row that owns a core-managed
                      subscription; null for tenant-created ones.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_subscription
                  scope_ref:
                    description: Webhook subscriptions can be scoped only to an enterprise or
                      client.
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  signing:
                    description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                      only, verified against the published JWKS."
                    type: string
                    enum:
                      - hmac
                      - asymmetric
                  status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  url:
                    type: string
                    format: uri
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: deleted
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.delete
      x-required-capability:
        - webhooks.manage
  /webhook-subscriptions/{subscription_id}/deliveries:
    get:
      summary: List webhook deliveries
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                enum:
                  - pending
                  - delivered
                  - failed
                  - retrying
                  - dlq
              - type: array
                items:
                  type: string
                  enum:
                    - pending
                    - delivered
                    - failed
                    - retrying
                    - dlq
        - name: event_id
          in: query
          required: false
          schema:
            description: Only the deliveries of this event (the first-access button status).
            type: string
            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - attempt_count: 1
                    attempts:
                      - attempt_number: 1
                        attempted_at: 2026-05-01T10:00:00Z
                        delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        duration_ms: 142
                        http_status_code: 200
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: delivery_attempt
                        response_body: ok
                    created_at: 2026-05-01T10:00:00Z
                    event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    last_attempt_at: 2026-05-01T10:00:00Z
                    next_retry_at: null
                    resource: webhook_delivery
                    status: delivered
                    subscription_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - subscription_id
                        - event_id
                        - status
                        - attempt_count
                        - last_attempt_at
                        - next_retry_at
                        - created_at
                        - attempts
                      type: object
                      additionalProperties: false
                      properties:
                        attempt_count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        attempts:
                          type: array
                          items:
                            required:
                              - id
                              - resource
                              - delivery_id
                              - attempt_number
                              - http_status_code
                              - response_body
                              - duration_ms
                              - attempted_at
                            type: object
                            additionalProperties: false
                            properties:
                              attempt_number:
                                type: integer
                                maximum: 9007199254740991
                                exclusiveMinimum: 0
                              attempted_at:
                                anyOf:
                                  - type: string
                                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                    format: date-time
                                  - type: string
                                    format: date-time
                              delivery_id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              duration_ms:
                                type: integer
                                minimum: 0
                                maximum: 9007199254740991
                              http_status_code:
                                anyOf:
                                  - type: integer
                                    minimum: 100
                                    maximum: 599
                                  - type: "null"
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              resource:
                                type: string
                                const: delivery_attempt
                              response_body:
                                anyOf:
                                  - type: string
                                  - type: "null"
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        event_id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        last_attempt_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        next_retry_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        resource:
                          type: string
                          const: webhook_delivery
                        status:
                          type: string
                          enum:
                            - pending
                            - delivered
                            - failed
                            - retrying
                            - dlq
                        subscription_id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - attempt_count: 1
                        attempts:
                          - attempt_number: 1
                            attempted_at: 2026-05-01T10:00:00Z
                            delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            duration_ms: 142
                            http_status_code: 200
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            resource: delivery_attempt
                            response_body: ok
                        created_at: 2026-05-01T10:00:00Z
                        event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        last_attempt_at: 2026-05-01T10:00:00Z
                        next_retry_at: null
                        resource: webhook_delivery
                        status: delivered
                        subscription_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.deliveries
      x-required-capability:
        - webhooks.read
  /webhook-subscriptions/{subscription_id}/deliveries/{delivery_id}:
    get:
      summary: Get webhook delivery
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                attempt_count: 1
                attempts:
                  - attempt_number: 1
                    attempted_at: 2026-05-01T10:00:00Z
                    delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    duration_ms: 142
                    http_status_code: 200
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    resource: delivery_attempt
                    response_body: ok
                created_at: 2026-05-01T10:00:00Z
                event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                last_attempt_at: 2026-05-01T10:00:00Z
                next_retry_at: null
                resource: webhook_delivery
                status: delivered
                subscription_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - id
                  - resource
                  - subscription_id
                  - event_id
                  - status
                  - attempt_count
                  - last_attempt_at
                  - next_retry_at
                  - created_at
                  - attempts
                type: object
                additionalProperties: false
                properties:
                  attempt_count:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  attempts:
                    type: array
                    items:
                      required:
                        - id
                        - resource
                        - delivery_id
                        - attempt_number
                        - http_status_code
                        - response_body
                        - duration_ms
                        - attempted_at
                      type: object
                      additionalProperties: false
                      properties:
                        attempt_number:
                          type: integer
                          maximum: 9007199254740991
                          exclusiveMinimum: 0
                        attempted_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        delivery_id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        duration_ms:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        http_status_code:
                          anyOf:
                            - type: integer
                              minimum: 100
                              maximum: 599
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        resource:
                          type: string
                          const: delivery_attempt
                        response_body:
                          anyOf:
                            - type: string
                            - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  event_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  last_attempt_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  next_retry_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_delivery
                  status:
                    type: string
                    enum:
                      - pending
                      - delivered
                      - failed
                      - retrying
                      - dlq
                  subscription_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - attempt_count: 1
                    attempts:
                      - attempt_number: 1
                        attempted_at: 2026-05-01T10:00:00Z
                        delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        duration_ms: 142
                        http_status_code: 200
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        resource: delivery_attempt
                        response_body: ok
                    created_at: 2026-05-01T10:00:00Z
                    event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    last_attempt_at: 2026-05-01T10:00:00Z
                    next_retry_at: null
                    resource: webhook_delivery
                    status: delivered
                    subscription_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.deliveries.get
      x-required-capability:
        - webhooks.read
  /webhook-subscriptions/{subscription_id}/deliveries/{delivery_id}/redeliver:
    post:
      description: "Schedules another attempt for an existing delivery that has not
        been delivered successfully. An already delivered row returns 409 with
        reason `webhook_delivery_already_delivered`; use event replay when an
        event must be delivered again after success. The subscription must be
        active when redelivery is scheduled, with one exception: a
        platform-managed subscription paused by the platform holds its
        deliveries, so the redelivery is accepted and held until the platform
        resumes it. A subscription you paused, or a deleted one, returns 409
        with reason `webhook_subscription_not_active` without changing the
        delivery. A subsequent pause of your own before the worker sends can
        still prevent delivery. Re-enable first, then use event replay to
        recover missed events. Track the returned delivery_id with the ordinary
        delivery read."
      summary: Redeliver webhook delivery
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: delivery_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                accepted: true
                delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - accepted
                  - delivery_id
                type: object
                additionalProperties: false
                properties:
                  accepted:
                    type: boolean
                    const: true
                  delivery_id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                examples:
                  - accepted: true
                    delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.redeliver
      x-required-capability:
        - webhooks.manage
  /webhook-subscriptions/{subscription_id}/disable:
    post:
      description: "Sets status to `paused`. Tenant subscriptions do not buffer events
        while paused: events published during the pause are not delivered and
        pending deliveries fail without a send attempt. After re-enabling, use
        event replay to recover events. Requires the current If-Match entity
        tag. Platform-managed subscriptions cannot be changed through this
        route."
      summary: Disable webhook subscription
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 2026-05-01T10:00:00Z
                event_types:
                  - operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kind: public
                managed_by: null
                resource: webhook_subscription
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                signing: hmac
                status: paused
                updated_at: 2026-05-01T10:00:00Z
                url: https://example.com/webhooks
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - url
                  - event_types
                  - status
                  - kind
                  - signing
                  - managed_by
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  etag:
                    type: string
                    minLength: 1
                  event_types:
                    type: array
                    items:
                      type: string
                      enum:
                        - "*"
                        - tenant.enterprise.admission_reviewed.v1
                        - tenant.enterprise.admitted.v1
                        - tenant.enterprise.activated.v1
                        - tenant.enterprise.updated.v1
                        - tenant.enterprise.suspended.v1
                        - tenant.enterprise.reactivated.v1
                        - tenant.enterprise.closed.v1
                        - tenant.enterprise.terminated.v1
                        - tenant.platform_operator.admitted.v1
                        - tenant.platform_operator.restricted.v1
                        - tenant.platform_operator.reactivated.v1
                        - tenant.platform_operator.offboarded.v1
                        - tenant.platform_operator.catalog_updated.v1
                        - tenant.master_account.created.v1
                        - tenant.master_account.suspended.v1
                        - tenant.master_account.closed.v1
                        - tenant.client.created.v1
                        - tenant.client.updated.v1
                        - tenant.client.suspended.v1
                        - tenant.client.reactivated.v1
                        - tenant.client.closed.v1
                        - tenant.client_account.created.v1
                        - tenant.client_account.suspended.v1
                        - tenant.client_account.reactivated.v1
                        - tenant.client_account.closed.v1
                        - ledger.transaction.posted.v1
                        - operations.withdrawal.requested.v1
                        - operations.withdrawal.admissible.v1
                        - operations.withdrawal.executing.v1
                        - operations.withdrawal.pending_approval.v1
                        - operations.withdrawal.pending_compliance.v1
                        - operations.withdrawal.approved.v1
                        - operations.withdrawal.settled.v1
                        - operations.withdrawal.failed.v1
                        - operations.withdrawal.cancelled.v1
                        - operations.conversion.requested.v1
                        - operations.conversion.admissible.v1
                        - operations.conversion.pending_approval.v1
                        - operations.conversion.pending_compliance.v1
                        - operations.conversion.approved.v1
                        - operations.conversion.settled.v1
                        - operations.conversion.failed.v1
                        - operations.conversion.cancelled.v1
                        - operations.external_settlement_conversion.pending_compliance.v1
                        - operations.internal_transfer.requested.v1
                        - operations.internal_transfer.admissible.v1
                        - operations.internal_transfer.pending_approval.v1
                        - operations.internal_transfer.pending_compliance.v1
                        - operations.internal_transfer.approved.v1
                        - operations.internal_transfer.settled.v1
                        - operations.internal_transfer.failed.v1
                        - operations.internal_transfer.cancelled.v1
                        - operations.on_ramp.requested.v1
                        - operations.on_ramp.admissible.v1
                        - operations.on_ramp.pending_approval.v1
                        - operations.on_ramp.pending_compliance.v1
                        - operations.on_ramp.approved.v1
                        - operations.on_ramp.settled.v1
                        - operations.on_ramp.failed.v1
                        - operations.on_ramp.cancelled.v1
                        - operations.off_ramp.requested.v1
                        - operations.off_ramp.admissible.v1
                        - operations.off_ramp.pending_approval.v1
                        - operations.off_ramp.pending_compliance.v1
                        - operations.off_ramp.approved.v1
                        - operations.off_ramp.settled.v1
                        - operations.off_ramp.failed.v1
                        - operations.off_ramp.cancelled.v1
                        - operations.deposit.requested.v1
                        - operations.deposit.admissible.v1
                        - operations.deposit.pending_approval.v1
                        - operations.deposit.pending_admission.v1
                        - operations.deposit.pending_compliance.v1
                        - operations.deposit.approved.v1
                        - operations.deposit.settled.v1
                        - operations.deposit.failed.v1
                        - operations.deposit.cancelled.v1
                        - rails.deposit.detected.v1
                        - rails.dispatch.acknowledged.v1
                        - rails.dispatch.rejected.v1
                        - rails.settlement.confirmed.v1
                        - kyc.verification.reviewed.v1
                        - loan.originated.v1
                        - loan.origination_failed.v1
                        - loan.margin_called.v1
                        - loan.margin_call_cleared.v1
                        - loan.liquidation_halted.v1
                        - loan.liquidated.v1
                        - loan.repaid.v1
                        - loan.extended.v1
                        - loan.closed.v1
                        - loan.force_closed.v1
                        - loan.reconciliation_discrepancy.v1
                        - tenant.enterprise.*.v1
                        - tenant.*.v1
                        - tenant.platform_operator.*.v1
                        - tenant.master_account.*.v1
                        - tenant.client.*.v1
                        - tenant.client_account.*.v1
                        - ledger.transaction.*.v1
                        - ledger.*.v1
                        - operations.withdrawal.*.v1
                        - operations.*.v1
                        - operations.conversion.*.v1
                        - operations.external_settlement_conversion.*.v1
                        - operations.internal_transfer.*.v1
                        - operations.on_ramp.*.v1
                        - operations.off_ramp.*.v1
                        - operations.deposit.*.v1
                        - rails.deposit.*.v1
                        - rails.*.v1
                        - rails.dispatch.*.v1
                        - rails.settlement.*.v1
                        - kyc.verification.*.v1
                        - kyc.*.v1
                        - loan.loan.*.v1
                        - loan.*.v1
                        - identity.human_actor.created.v1
                        - identity.human_actor.pending_created.v1
                        - identity.human_actor.activated.v1
                        - identity.human_actor.suspended.v1
                        - identity.human_actor.reactivated.v1
                        - identity.human_actor.deactivated.v1
                        - identity.human_actor.updated.v1
                        - identity.human_actor.federation_bound.v1
                        - identity.human_actor.*.v1
                        - identity.human_actor.access_resend_requested.v1
                        - identity.human_actor.recovery_requested.v1
                    minItems: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kind:
                    description: "Which catalog classes the subscription admits: public → public
                      events; identity → public and identity events; command →
                      command events only."
                    type: string
                    enum:
                      - public
                      - identity
                      - command
                  managed_by:
                    description: identity_provider_id of the IdP row that owns a core-managed
                      subscription; null for tenant-created ones.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_subscription
                  scope_ref:
                    description: Webhook subscriptions can be scoped only to an enterprise or
                      client.
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  signing:
                    description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                      only, verified against the published JWKS."
                    type: string
                    enum:
                      - hmac
                      - asymmetric
                  status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  url:
                    type: string
                    format: uri
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: paused
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.disable
      x-required-capability:
        - webhooks.manage
  /webhook-subscriptions/{subscription_id}/enable:
    post:
      description: Activates a paused tenant-created subscription and requires the
        current If-Match entity tag. A deleted subscription cannot be
        reactivated and returns 409 with reason
        `webhook_subscription_not_active`. Enabling an identity event stream
        additionally requires users.read covering the subscription scope.
        Platform-managed subscriptions cannot be changed through this route.
      summary: Enable webhook subscription
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                created_at: 2026-05-01T10:00:00Z
                etag: 2026-05-01T10:00:00Z
                event_types:
                  - operations.withdrawal.settled.v1
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                kind: public
                managed_by: null
                resource: webhook_subscription
                scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                signing: hmac
                status: active
                updated_at: 2026-05-01T10:00:00Z
                url: https://example.com/webhooks
              schema:
                required:
                  - id
                  - resource
                  - scope_ref
                  - url
                  - event_types
                  - status
                  - kind
                  - signing
                  - managed_by
                  - created_at
                  - updated_at
                  - etag
                type: object
                additionalProperties: false
                properties:
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  etag:
                    type: string
                    minLength: 1
                  event_types:
                    type: array
                    items:
                      type: string
                      enum:
                        - "*"
                        - tenant.enterprise.admission_reviewed.v1
                        - tenant.enterprise.admitted.v1
                        - tenant.enterprise.activated.v1
                        - tenant.enterprise.updated.v1
                        - tenant.enterprise.suspended.v1
                        - tenant.enterprise.reactivated.v1
                        - tenant.enterprise.closed.v1
                        - tenant.enterprise.terminated.v1
                        - tenant.platform_operator.admitted.v1
                        - tenant.platform_operator.restricted.v1
                        - tenant.platform_operator.reactivated.v1
                        - tenant.platform_operator.offboarded.v1
                        - tenant.platform_operator.catalog_updated.v1
                        - tenant.master_account.created.v1
                        - tenant.master_account.suspended.v1
                        - tenant.master_account.closed.v1
                        - tenant.client.created.v1
                        - tenant.client.updated.v1
                        - tenant.client.suspended.v1
                        - tenant.client.reactivated.v1
                        - tenant.client.closed.v1
                        - tenant.client_account.created.v1
                        - tenant.client_account.suspended.v1
                        - tenant.client_account.reactivated.v1
                        - tenant.client_account.closed.v1
                        - ledger.transaction.posted.v1
                        - operations.withdrawal.requested.v1
                        - operations.withdrawal.admissible.v1
                        - operations.withdrawal.executing.v1
                        - operations.withdrawal.pending_approval.v1
                        - operations.withdrawal.pending_compliance.v1
                        - operations.withdrawal.approved.v1
                        - operations.withdrawal.settled.v1
                        - operations.withdrawal.failed.v1
                        - operations.withdrawal.cancelled.v1
                        - operations.conversion.requested.v1
                        - operations.conversion.admissible.v1
                        - operations.conversion.pending_approval.v1
                        - operations.conversion.pending_compliance.v1
                        - operations.conversion.approved.v1
                        - operations.conversion.settled.v1
                        - operations.conversion.failed.v1
                        - operations.conversion.cancelled.v1
                        - operations.external_settlement_conversion.pending_compliance.v1
                        - operations.internal_transfer.requested.v1
                        - operations.internal_transfer.admissible.v1
                        - operations.internal_transfer.pending_approval.v1
                        - operations.internal_transfer.pending_compliance.v1
                        - operations.internal_transfer.approved.v1
                        - operations.internal_transfer.settled.v1
                        - operations.internal_transfer.failed.v1
                        - operations.internal_transfer.cancelled.v1
                        - operations.on_ramp.requested.v1
                        - operations.on_ramp.admissible.v1
                        - operations.on_ramp.pending_approval.v1
                        - operations.on_ramp.pending_compliance.v1
                        - operations.on_ramp.approved.v1
                        - operations.on_ramp.settled.v1
                        - operations.on_ramp.failed.v1
                        - operations.on_ramp.cancelled.v1
                        - operations.off_ramp.requested.v1
                        - operations.off_ramp.admissible.v1
                        - operations.off_ramp.pending_approval.v1
                        - operations.off_ramp.pending_compliance.v1
                        - operations.off_ramp.approved.v1
                        - operations.off_ramp.settled.v1
                        - operations.off_ramp.failed.v1
                        - operations.off_ramp.cancelled.v1
                        - operations.deposit.requested.v1
                        - operations.deposit.admissible.v1
                        - operations.deposit.pending_approval.v1
                        - operations.deposit.pending_admission.v1
                        - operations.deposit.pending_compliance.v1
                        - operations.deposit.approved.v1
                        - operations.deposit.settled.v1
                        - operations.deposit.failed.v1
                        - operations.deposit.cancelled.v1
                        - rails.deposit.detected.v1
                        - rails.dispatch.acknowledged.v1
                        - rails.dispatch.rejected.v1
                        - rails.settlement.confirmed.v1
                        - kyc.verification.reviewed.v1
                        - loan.originated.v1
                        - loan.origination_failed.v1
                        - loan.margin_called.v1
                        - loan.margin_call_cleared.v1
                        - loan.liquidation_halted.v1
                        - loan.liquidated.v1
                        - loan.repaid.v1
                        - loan.extended.v1
                        - loan.closed.v1
                        - loan.force_closed.v1
                        - loan.reconciliation_discrepancy.v1
                        - tenant.enterprise.*.v1
                        - tenant.*.v1
                        - tenant.platform_operator.*.v1
                        - tenant.master_account.*.v1
                        - tenant.client.*.v1
                        - tenant.client_account.*.v1
                        - ledger.transaction.*.v1
                        - ledger.*.v1
                        - operations.withdrawal.*.v1
                        - operations.*.v1
                        - operations.conversion.*.v1
                        - operations.external_settlement_conversion.*.v1
                        - operations.internal_transfer.*.v1
                        - operations.on_ramp.*.v1
                        - operations.off_ramp.*.v1
                        - operations.deposit.*.v1
                        - rails.deposit.*.v1
                        - rails.*.v1
                        - rails.dispatch.*.v1
                        - rails.settlement.*.v1
                        - kyc.verification.*.v1
                        - kyc.*.v1
                        - loan.loan.*.v1
                        - loan.*.v1
                        - identity.human_actor.created.v1
                        - identity.human_actor.pending_created.v1
                        - identity.human_actor.activated.v1
                        - identity.human_actor.suspended.v1
                        - identity.human_actor.reactivated.v1
                        - identity.human_actor.deactivated.v1
                        - identity.human_actor.updated.v1
                        - identity.human_actor.federation_bound.v1
                        - identity.human_actor.*.v1
                        - identity.human_actor.access_resend_requested.v1
                        - identity.human_actor.recovery_requested.v1
                    minItems: 1
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  kind:
                    description: "Which catalog classes the subscription admits: public → public
                      events; identity → public and identity events; command →
                      command events only."
                    type: string
                    enum:
                      - public
                      - identity
                      - command
                  managed_by:
                    description: identity_provider_id of the IdP row that owns a core-managed
                      subscription; null for tenant-created ones.
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  resource:
                    type: string
                    const: webhook_subscription
                  scope_ref:
                    description: Webhook subscriptions can be scoped only to an enterprise or
                      client.
                    anyOf:
                      - type: string
                        pattern: ^(enterprises)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: string
                        pattern: ^(clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  signing:
                    description: "hmac: v1 HMAC header plus the v2 Ed25519 header; asymmetric: v2
                      only, verified against the published JWKS."
                    type: string
                    enum:
                      - hmac
                      - asymmetric
                  status:
                    type: string
                    enum:
                      - active
                      - paused
                      - deleted
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  url:
                    type: string
                    format: uri
                examples:
                  - created_at: 2026-05-01T10:00:00Z
                    etag: 2026-05-01T10:00:00Z
                    event_types:
                      - operations.withdrawal.settled.v1
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: public
                    managed_by: null
                    resource: webhook_subscription
                    scope_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    signing: hmac
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                    url: https://example.com/webhooks
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "412":
          $ref: "#/components/responses/EdgePreconditionFailed"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.enable
      x-required-capability:
        - webhooks.manage
  /webhook-subscriptions/{subscription_id}/test:
    post:
      description: Sends a synthetic test event to an active tenant-managed
        subscription and returns the delivery snapshot, including the first
        attempt. Failed attempts follow the ordinary retry and dead-letter flow.
        A paused or deleted subscription returns 409 with reason
        `webhook_subscription_not_active`; a platform-managed subscription
        returns 409 with reason `subscription_managed`.
      summary: Send webhook test delivery
      tags:
        - Distribution
        - Webhook Subscriptions
      security:
        - BearerAuth: []
      parameters:
        - name: subscription_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                accepted: true
                delivery:
                  attempt_count: 1
                  attempts:
                    - attempt_number: 1
                      attempted_at: 2026-05-01T10:00:00Z
                      delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      duration_ms: 142
                      http_status_code: 200
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      resource: delivery_attempt
                      response_body: ok
                  created_at: 2026-05-01T10:00:00Z
                  event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  last_attempt_at: 2026-05-01T10:00:00Z
                  next_retry_at: null
                  resource: webhook_delivery
                  status: delivered
                  subscription_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              schema:
                required:
                  - accepted
                  - delivery
                type: object
                additionalProperties: false
                properties:
                  accepted:
                    type: boolean
                    const: true
                  delivery:
                    required:
                      - id
                      - resource
                      - subscription_id
                      - event_id
                      - status
                      - attempt_count
                      - last_attempt_at
                      - next_retry_at
                      - created_at
                      - attempts
                    type: object
                    additionalProperties: false
                    properties:
                      attempt_count:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      attempts:
                        type: array
                        items:
                          required:
                            - id
                            - resource
                            - delivery_id
                            - attempt_number
                            - http_status_code
                            - response_body
                            - duration_ms
                            - attempted_at
                          type: object
                          additionalProperties: false
                          properties:
                            attempt_number:
                              type: integer
                              maximum: 9007199254740991
                              exclusiveMinimum: 0
                            attempted_at:
                              anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            delivery_id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            duration_ms:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            http_status_code:
                              anyOf:
                                - type: integer
                                  minimum: 100
                                  maximum: 599
                                - type: "null"
                            id:
                              type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            resource:
                              type: string
                              const: delivery_attempt
                            response_body:
                              anyOf:
                                - type: string
                                - type: "null"
                      created_at:
                        anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      event_id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      last_attempt_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      next_retry_at:
                        anyOf:
                          - anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          - type: "null"
                      resource:
                        type: string
                        const: webhook_delivery
                      status:
                        type: string
                        enum:
                          - pending
                          - delivered
                          - failed
                          - retrying
                          - dlq
                      subscription_id:
                        type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                examples:
                  - accepted: true
                    delivery:
                      attempt_count: 1
                      attempts:
                        - attempt_number: 1
                          attempted_at: 2026-05-01T10:00:00Z
                          delivery_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          duration_ms: 142
                          http_status_code: 200
                          id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          resource: delivery_attempt
                          response_body: ok
                      created_at: 2026-05-01T10:00:00Z
                      event_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      last_attempt_at: 2026-05-01T10:00:00Z
                      next_retry_at: null
                      resource: webhook_delivery
                      status: delivered
                      subscription_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: webhook_subscriptions.test
      x-required-capability:
        - webhooks.manage
  /withdrawal-destinations:
    get:
      description: Lists withdrawal destinations for the selected rail. Crypto lists
        require `scope_ref` for the topology-scoped address book. Fiat lists
        require `account_ref`; the pooled fiat route owner is derived
        server-side and is not part of the request surface.
      summary: List withdrawal destinations
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: scope_ref
          in: query
          required: false
          schema:
            description: Topology scope of the crypto address book. Required when
              rail_class=crypto; ignored for fiat.
            type: string
            pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - active
              - disabled
              - retired
        - name: asset
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - name: currency
          in: query
          required: false
          schema:
            description: Currency code (ISO-4217 or on-chain ticker)
            type: string
            pattern: ^[A-Z0-9]{1,16}$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - rail_class
                        - status
                        - scope_ref
                        - created_at
                        - updated_at
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          anyOf:
                            - description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            - type: "null"
                        created_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                        crypto_routing:
                          anyOf:
                            - required:
                                - asset
                                - network
                                - destination
                                - label
                              type: object
                              additionalProperties: false
                              properties:
                                asset:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                destination:
                                  required:
                                    - address
                                    - memo
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    address:
                                      type: string
                                      minLength: 1
                                      maxLength: 256
                                    memo:
                                      anyOf:
                                        - type: string
                                        - type: "null"
                                label:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                                network:
                                  type: string
                                  minLength: 1
                            - type: "null"
                        fiat_routing:
                          anyOf:
                            - required:
                                - fiat_rail
                                - method
                                - currency
                                - beneficiary_name
                                - bank_coordinates
                                - reference_hint
                              type: object
                              additionalProperties: false
                              properties:
                                bank_coordinates:
                                  oneOf:
                                    - required:
                                        - scheme
                                        - iban
                                        - bic
                                        - account_holder_name
                                        - bank_name
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        account_holder_name:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        bank_address:
                                          description: Postal address of the bank that holds the account.
                                          anyOf:
                                            - required:
                                                - lines
                                                - city
                                                - region
                                                - postal_code
                                                - country
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                city:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                country:
                                                  type: string
                                                  pattern: ^[A-Z]{2}$
                                                lines:
                                                  type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  maxItems: 4
                                                  minItems: 1
                                                postal_code:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 32
                                                    - type: "null"
                                                region:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    - type: "null"
                                            - type: "null"
                                        bank_name:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                        bic:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 11
                                            - type: "null"
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        iban:
                                          type: string
                                          minLength: 1
                                          maxLength: 34
                                        scheme:
                                          type: string
                                          const: iban
                                    - required:
                                        - scheme
                                        - account_number
                                        - routing_codes
                                        - bic
                                        - account_holder_name
                                        - bank_name
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        account_holder_name:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        account_number:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        account_type:
                                          description: Checking or savings. Required by some payout rails (a US domestic
                                            wire); null or absent where the rail
                                            has no such concept.
                                          anyOf:
                                            - type: string
                                              enum:
                                                - checking
                                                - savings
                                            - type: "null"
                                        bank_address:
                                          description: Postal address of the bank that holds the account.
                                          anyOf:
                                            - required:
                                                - lines
                                                - city
                                                - region
                                                - postal_code
                                                - country
                                              type: object
                                              additionalProperties: false
                                              properties:
                                                city:
                                                  type: string
                                                  minLength: 1
                                                  maxLength: 140
                                                country:
                                                  type: string
                                                  pattern: ^[A-Z]{2}$
                                                lines:
                                                  type: array
                                                  items:
                                                    type: string
                                                    minLength: 1
                                                    maxLength: 140
                                                  maxItems: 4
                                                  minItems: 1
                                                postal_code:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 32
                                                    - type: "null"
                                                region:
                                                  anyOf:
                                                    - type: string
                                                      minLength: 1
                                                      maxLength: 140
                                                    - type: "null"
                                            - type: "null"
                                        bank_name:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                        bic:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 11
                                            - type: "null"
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        routing_codes:
                                          type: array
                                          items:
                                            required:
                                              - type
                                              - value
                                            type: object
                                            additionalProperties: false
                                            properties:
                                              type:
                                                type: string
                                                minLength: 1
                                                maxLength: 64
                                              value:
                                                type: string
                                                minLength: 1
                                                maxLength: 64
                                          maxItems: 16
                                          minItems: 1
                                        scheme:
                                          type: string
                                          const: local_account
                                beneficiary_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                currency:
                                  description: Currency code (ISO-4217 or on-chain ticker)
                                  type: string
                                  pattern: ^[A-Z0-9]{1,16}$
                                fiat_rail:
                                  type: string
                                  enum:
                                    - sepa_credit_transfer
                                    - faster_payments
                                    - swift
                                    - local_bank_transfer
                                    - fedwire
                                method:
                                  type: string
                                  enum:
                                    - bank_transfer
                                reference_hint:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        label:
                          anyOf:
                            - type: string
                            - type: "null"
                        rail_class:
                          type: string
                          enum:
                            - fiat
                            - crypto
                        scope_ref:
                          type: string
                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        status:
                          type: string
                          enum:
                            - active
                            - disabled
                            - retired
                        updated_at:
                          type: string
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                          format: date-time
                  next_page_token:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                examples:
                  - items:
                      - asset: USDC
                        created_at: 2026-05-01T10:00:00Z
                        crypto_routing:
                          asset: USDC
                          destination:
                            address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                            memo: null
                          label: My ETH wallet
                          network: ethereum
                        fiat_routing: null
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        label: My ETH wallet
                        rail_class: crypto
                        scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        status: active
                        updated_at: 2026-05-01T10:00:00Z
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.list
      x-required-capability:
        - withdrawal_destinations.read
    post:
      description: "Registers a crypto withdrawal destination with typed `{asset,
        network, destination: {address, memo}, label}` routing and `scope_ref`.
        Fiat destination creation requires `account_ref` and canonical fiat
        rails routing `{fiat_rail, method, currency, beneficiary_name,
        bank_coordinates, reference_hint}`; the pooled fiat route owner is
        derived server-side. Supply `Idempotency-Key` for replay-safe creation;
        it takes precedence over body `idempotency_key`. Fiat creation requires
        a key in either location. Crypto creation generates a key when both are
        absent, so retrying without a caller-supplied key does not replay the
        original request."
      summary: Register withdrawal destination
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              crypto_routing:
                asset: USDC
                destination:
                  address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                  memo: null
                label: My ETH wallet
                network: ethereum
              rail_class: crypto
              scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              examples:
                - crypto_routing:
                    asset: USDC
                    destination:
                      address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                      memo: null
                    label: My ETH wallet
                    network: ethereum
                  rail_class: crypto
                  scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              oneOf:
                - required:
                    - rail_class
                    - scope_ref
                    - crypto_routing
                  type: object
                  additionalProperties: false
                  properties:
                    crypto_routing:
                      required:
                        - asset
                        - network
                        - destination
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        destination:
                          required:
                            - address
                            - memo
                          type: object
                          additionalProperties: false
                          properties:
                            address:
                              type: string
                              minLength: 1
                              maxLength: 256
                            memo:
                              anyOf:
                                - type: string
                                - type: "null"
                        label:
                          anyOf:
                            - type: string
                            - type: "null"
                        network:
                          type: string
                          minLength: 1
                    idempotency_key:
                      type: string
                      minLength: 1
                    rail_class:
                      type: string
                      const: crypto
                    scope_ref:
                      type: string
                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                - required:
                    - rail_class
                    - account_ref
                    - fiat_routing
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    fiat_routing:
                      required:
                        - fiat_rail
                        - method
                        - currency
                        - beneficiary_name
                        - bank_coordinates
                        - reference_hint
                      type: object
                      additionalProperties: false
                      properties:
                        bank_coordinates:
                          oneOf:
                            - required:
                                - scheme
                                - iban
                                - bic
                                - account_holder_name
                                - bank_name
                                - country
                              type: object
                              additionalProperties: false
                              properties:
                                account_holder_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                bank_address:
                                  description: Postal address of the bank that holds the account.
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                bank_name:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                                bic:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 11
                                    - type: "null"
                                country:
                                  type: string
                                  pattern: ^[A-Z]{2}$
                                iban:
                                  type: string
                                  minLength: 1
                                  maxLength: 34
                                scheme:
                                  type: string
                                  const: iban
                            - required:
                                - scheme
                                - account_number
                                - routing_codes
                                - bic
                                - account_holder_name
                                - bank_name
                                - country
                              type: object
                              additionalProperties: false
                              properties:
                                account_holder_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                account_number:
                                  type: string
                                  minLength: 1
                                  maxLength: 64
                                account_type:
                                  description: Checking or savings. Required by some payout rails (a US domestic
                                    wire); null or absent where the rail has no
                                    such concept.
                                  anyOf:
                                    - type: string
                                      enum:
                                        - checking
                                        - savings
                                    - type: "null"
                                bank_address:
                                  description: Postal address of the bank that holds the account.
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                bank_name:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                                bic:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 11
                                    - type: "null"
                                country:
                                  type: string
                                  pattern: ^[A-Z]{2}$
                                routing_codes:
                                  type: array
                                  items:
                                    required:
                                      - type
                                      - value
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      type:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      value:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                  maxItems: 16
                                  minItems: 1
                                scheme:
                                  type: string
                                  const: local_account
                        beneficiary_name:
                          type: string
                          minLength: 1
                          maxLength: 140
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        fiat_rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                        method:
                          type: string
                          enum:
                            - bank_transfer
                        reference_hint:
                          anyOf:
                            - type: string
                              minLength: 1
                              maxLength: 140
                            - type: "null"
                    idempotency_key:
                      type: string
                      minLength: 1
                    rail_class:
                      type: string
                      const: fiat
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  destination:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  label: My ETH wallet
                  network: ethereum
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                label: My ETH wallet
                rail_class: crypto
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - destination
                          - label
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          destination:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          label:
                            anyOf:
                              - type: string
                              - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - fiat_rail
                          - method
                          - currency
                          - beneficiary_name
                          - bank_coordinates
                          - reference_hint
                        type: object
                        additionalProperties: false
                        properties:
                          bank_coordinates:
                            oneOf:
                              - required:
                                  - scheme
                                  - iban
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  iban:
                                    type: string
                                    minLength: 1
                                    maxLength: 34
                                  scheme:
                                    type: string
                                    const: iban
                              - required:
                                  - scheme
                                  - account_number
                                  - routing_codes
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  account_number:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  account_type:
                                    description: Checking or savings. Required by some payout rails (a US domestic
                                      wire); null or absent where the rail has
                                      no such concept.
                                    anyOf:
                                      - type: string
                                        enum:
                                          - checking
                                          - savings
                                      - type: "null"
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  routing_codes:
                                    type: array
                                    items:
                                      required:
                                        - type
                                        - value
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        type:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                    maxItems: 16
                                    minItems: 1
                                  scheme:
                                    type: string
                                    const: local_account
                          beneficiary_name:
                            type: string
                            minLength: 1
                            maxLength: 140
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          method:
                            type: string
                            enum:
                              - bank_transfer
                          reference_hint:
                            anyOf:
                              - type: string
                                minLength: 1
                                maxLength: 140
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  label:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.create
      x-required-capability:
        - withdrawal_destinations.create
  /withdrawal-destinations/{destination_id}:
    parameters:
      - name: destination_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: Reads a withdrawal destination by id. The `rail_class` query
        parameter is required so edge can route directly to the selected
        backend. Fiat reads also require `account_ref` as the producer scope
        field; the pooled fiat route owner is derived server-side.
      summary: Get withdrawal destination
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - name: destination_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  destination:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  label: My ETH wallet
                  network: ethereum
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                label: My ETH wallet
                rail_class: crypto
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - destination
                          - label
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          destination:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          label:
                            anyOf:
                              - type: string
                              - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - fiat_rail
                          - method
                          - currency
                          - beneficiary_name
                          - bank_coordinates
                          - reference_hint
                        type: object
                        additionalProperties: false
                        properties:
                          bank_coordinates:
                            oneOf:
                              - required:
                                  - scheme
                                  - iban
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  iban:
                                    type: string
                                    minLength: 1
                                    maxLength: 34
                                  scheme:
                                    type: string
                                    const: iban
                              - required:
                                  - scheme
                                  - account_number
                                  - routing_codes
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  account_number:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  account_type:
                                    description: Checking or savings. Required by some payout rails (a US domestic
                                      wire); null or absent where the rail has
                                      no such concept.
                                    anyOf:
                                      - type: string
                                        enum:
                                          - checking
                                          - savings
                                      - type: "null"
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  routing_codes:
                                    type: array
                                    items:
                                      required:
                                        - type
                                        - value
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        type:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                    maxItems: 16
                                    minItems: 1
                                  scheme:
                                    type: string
                                    const: local_account
                          beneficiary_name:
                            type: string
                            minLength: 1
                            maxLength: 140
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          method:
                            type: string
                            enum:
                              - bank_transfer
                          reference_hint:
                            anyOf:
                              - type: string
                                minLength: 1
                                maxLength: 140
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  label:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.get
      x-required-capability:
        - withdrawal_destinations.read
    patch:
      description: "Updates a crypto withdrawal destination with typed `{asset,
        network, destination: {address, memo}, label}` routing. Fiat updates
        require `account_ref` and canonical fiat rails routing `{fiat_rail,
        method, currency, beneficiary_name, bank_coordinates, reference_hint}`.
        Fiat updates require an idempotency key in the `Idempotency-Key` header
        or body `idempotency_key`; the header takes precedence. Crypto updates
        do not use an idempotency key. PATCH requests are not replayed by the
        edge idempotency interceptor; a fiat update uses the key in
        rails-router."
      summary: Update withdrawal destination
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - name: destination_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            example:
              crypto_routing:
                asset: USDC
                destination:
                  address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                  memo: null
                label: My Polygon wallet
                network: polygon
              rail_class: crypto
            schema:
              examples:
                - crypto_routing:
                    asset: USDC
                    destination:
                      address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                      memo: null
                    label: My Polygon wallet
                    network: polygon
                  rail_class: crypto
              oneOf:
                - required:
                    - rail_class
                    - crypto_routing
                  type: object
                  additionalProperties: false
                  properties:
                    crypto_routing:
                      required:
                        - asset
                        - network
                        - destination
                      type: object
                      additionalProperties: false
                      properties:
                        asset:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        destination:
                          required:
                            - address
                            - memo
                          type: object
                          additionalProperties: false
                          properties:
                            address:
                              type: string
                              minLength: 1
                              maxLength: 256
                            memo:
                              anyOf:
                                - type: string
                                - type: "null"
                        label:
                          anyOf:
                            - type: string
                            - type: "null"
                        network:
                          type: string
                          minLength: 1
                    rail_class:
                      type: string
                      const: crypto
                - required:
                    - rail_class
                    - account_ref
                    - fiat_routing
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    fiat_routing:
                      required:
                        - fiat_rail
                        - method
                        - currency
                        - beneficiary_name
                        - bank_coordinates
                        - reference_hint
                      type: object
                      additionalProperties: false
                      properties:
                        bank_coordinates:
                          oneOf:
                            - required:
                                - scheme
                                - iban
                                - bic
                                - account_holder_name
                                - bank_name
                                - country
                              type: object
                              additionalProperties: false
                              properties:
                                account_holder_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                bank_address:
                                  description: Postal address of the bank that holds the account.
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                bank_name:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                                bic:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 11
                                    - type: "null"
                                country:
                                  type: string
                                  pattern: ^[A-Z]{2}$
                                iban:
                                  type: string
                                  minLength: 1
                                  maxLength: 34
                                scheme:
                                  type: string
                                  const: iban
                            - required:
                                - scheme
                                - account_number
                                - routing_codes
                                - bic
                                - account_holder_name
                                - bank_name
                                - country
                              type: object
                              additionalProperties: false
                              properties:
                                account_holder_name:
                                  type: string
                                  minLength: 1
                                  maxLength: 140
                                account_number:
                                  type: string
                                  minLength: 1
                                  maxLength: 64
                                account_type:
                                  description: Checking or savings. Required by some payout rails (a US domestic
                                    wire); null or absent where the rail has no
                                    such concept.
                                  anyOf:
                                    - type: string
                                      enum:
                                        - checking
                                        - savings
                                    - type: "null"
                                bank_address:
                                  description: Postal address of the bank that holds the account.
                                  anyOf:
                                    - required:
                                        - lines
                                        - city
                                        - region
                                        - postal_code
                                        - country
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        city:
                                          type: string
                                          minLength: 1
                                          maxLength: 140
                                        country:
                                          type: string
                                          pattern: ^[A-Z]{2}$
                                        lines:
                                          type: array
                                          items:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          maxItems: 4
                                          minItems: 1
                                        postal_code:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 32
                                            - type: "null"
                                        region:
                                          anyOf:
                                            - type: string
                                              minLength: 1
                                              maxLength: 140
                                            - type: "null"
                                    - type: "null"
                                bank_name:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 140
                                    - type: "null"
                                bic:
                                  anyOf:
                                    - type: string
                                      minLength: 1
                                      maxLength: 11
                                    - type: "null"
                                country:
                                  type: string
                                  pattern: ^[A-Z]{2}$
                                routing_codes:
                                  type: array
                                  items:
                                    required:
                                      - type
                                      - value
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      type:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                      value:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                  maxItems: 16
                                  minItems: 1
                                scheme:
                                  type: string
                                  const: local_account
                        beneficiary_name:
                          type: string
                          minLength: 1
                          maxLength: 140
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        fiat_rail:
                          type: string
                          enum:
                            - sepa_credit_transfer
                            - faster_payments
                            - swift
                            - local_bank_transfer
                            - fedwire
                        method:
                          type: string
                          enum:
                            - bank_transfer
                        reference_hint:
                          anyOf:
                            - type: string
                              minLength: 1
                              maxLength: 140
                            - type: "null"
                    idempotency_key:
                      type: string
                      minLength: 1
                    rail_class:
                      type: string
                      const: fiat
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  destination:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  label: My ETH wallet
                  network: ethereum
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                label: My ETH wallet
                rail_class: crypto
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - destination
                          - label
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          destination:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          label:
                            anyOf:
                              - type: string
                              - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - fiat_rail
                          - method
                          - currency
                          - beneficiary_name
                          - bank_coordinates
                          - reference_hint
                        type: object
                        additionalProperties: false
                        properties:
                          bank_coordinates:
                            oneOf:
                              - required:
                                  - scheme
                                  - iban
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  iban:
                                    type: string
                                    minLength: 1
                                    maxLength: 34
                                  scheme:
                                    type: string
                                    const: iban
                              - required:
                                  - scheme
                                  - account_number
                                  - routing_codes
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  account_number:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  account_type:
                                    description: Checking or savings. Required by some payout rails (a US domestic
                                      wire); null or absent where the rail has
                                      no such concept.
                                    anyOf:
                                      - type: string
                                        enum:
                                          - checking
                                          - savings
                                      - type: "null"
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  routing_codes:
                                    type: array
                                    items:
                                      required:
                                        - type
                                        - value
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        type:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                    maxItems: 16
                                    minItems: 1
                                  scheme:
                                    type: string
                                    const: local_account
                          beneficiary_name:
                            type: string
                            minLength: 1
                            maxLength: 140
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          method:
                            type: string
                            enum:
                              - bank_transfer
                          reference_hint:
                            anyOf:
                              - type: string
                                minLength: 1
                                maxLength: 140
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  label:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.update
      x-required-capability:
        - withdrawal_destinations.manage
  /withdrawal-destinations/{destination_id}/disable:
    post:
      description: Changes withdrawal destination state. The `rail_class` query
        parameter is required so edge can route directly to the selected
        backend. Fiat state changes also require `account_ref`. Fiat state
        changes require an idempotency key in the `Idempotency-Key` header or
        query `idempotency_key`; the header takes precedence. Crypto state
        changes do not use an idempotency key in the crypto path. With an
        Idempotency-Key header, the edge interceptor can replay the original
        POST response.
      summary: Disable withdrawal destination
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - name: destination_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: idempotency_key
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  destination:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  label: My ETH wallet
                  network: ethereum
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                label: My ETH wallet
                rail_class: crypto
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - destination
                          - label
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          destination:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          label:
                            anyOf:
                              - type: string
                              - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - fiat_rail
                          - method
                          - currency
                          - beneficiary_name
                          - bank_coordinates
                          - reference_hint
                        type: object
                        additionalProperties: false
                        properties:
                          bank_coordinates:
                            oneOf:
                              - required:
                                  - scheme
                                  - iban
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  iban:
                                    type: string
                                    minLength: 1
                                    maxLength: 34
                                  scheme:
                                    type: string
                                    const: iban
                              - required:
                                  - scheme
                                  - account_number
                                  - routing_codes
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  account_number:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  account_type:
                                    description: Checking or savings. Required by some payout rails (a US domestic
                                      wire); null or absent where the rail has
                                      no such concept.
                                    anyOf:
                                      - type: string
                                        enum:
                                          - checking
                                          - savings
                                      - type: "null"
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  routing_codes:
                                    type: array
                                    items:
                                      required:
                                        - type
                                        - value
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        type:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                    maxItems: 16
                                    minItems: 1
                                  scheme:
                                    type: string
                                    const: local_account
                          beneficiary_name:
                            type: string
                            minLength: 1
                            maxLength: 140
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          method:
                            type: string
                            enum:
                              - bank_transfer
                          reference_hint:
                            anyOf:
                              - type: string
                                minLength: 1
                                maxLength: 140
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  label:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.disable
      x-required-capability:
        - withdrawal_destinations.manage
  /withdrawal-destinations/{destination_id}/enable:
    post:
      description: Changes withdrawal destination state. The `rail_class` query
        parameter is required so edge can route directly to the selected
        backend. Fiat state changes also require `account_ref`. Fiat state
        changes require an idempotency key in the `Idempotency-Key` header or
        query `idempotency_key`; the header takes precedence. Crypto state
        changes do not use an idempotency key in the crypto path. With an
        Idempotency-Key header, the edge interceptor can replay the original
        POST response.
      summary: Enable withdrawal destination
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - name: destination_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: idempotency_key
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  destination:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  label: My ETH wallet
                  network: ethereum
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                label: My ETH wallet
                rail_class: crypto
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - destination
                          - label
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          destination:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          label:
                            anyOf:
                              - type: string
                              - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - fiat_rail
                          - method
                          - currency
                          - beneficiary_name
                          - bank_coordinates
                          - reference_hint
                        type: object
                        additionalProperties: false
                        properties:
                          bank_coordinates:
                            oneOf:
                              - required:
                                  - scheme
                                  - iban
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  iban:
                                    type: string
                                    minLength: 1
                                    maxLength: 34
                                  scheme:
                                    type: string
                                    const: iban
                              - required:
                                  - scheme
                                  - account_number
                                  - routing_codes
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  account_number:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  account_type:
                                    description: Checking or savings. Required by some payout rails (a US domestic
                                      wire); null or absent where the rail has
                                      no such concept.
                                    anyOf:
                                      - type: string
                                        enum:
                                          - checking
                                          - savings
                                      - type: "null"
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  routing_codes:
                                    type: array
                                    items:
                                      required:
                                        - type
                                        - value
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        type:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                    maxItems: 16
                                    minItems: 1
                                  scheme:
                                    type: string
                                    const: local_account
                          beneficiary_name:
                            type: string
                            minLength: 1
                            maxLength: 140
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          method:
                            type: string
                            enum:
                              - bank_transfer
                          reference_hint:
                            anyOf:
                              - type: string
                                minLength: 1
                                maxLength: 140
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  label:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.enable
      x-required-capability:
        - withdrawal_destinations.manage
  /withdrawal-destinations/{destination_id}/retire:
    post:
      description: Changes withdrawal destination state. The `rail_class` query
        parameter is required so edge can route directly to the selected
        backend. Fiat state changes also require `account_ref`. Fiat state
        changes require an idempotency key in the `Idempotency-Key` header or
        query `idempotency_key`; the header takes precedence. Crypto state
        changes do not use an idempotency key in the crypto path. With an
        Idempotency-Key header, the edge interceptor can replay the original
        POST response.
      summary: Retire withdrawal destination
      tags:
        - Distribution
        - Withdrawal Destinations
      security:
        - BearerAuth: []
      parameters:
        - name: destination_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: rail_class
          in: query
          required: true
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - name: account_ref
          in: query
          required: false
          schema:
            description: Operating account scope. Required when rail_class=fiat; ignored for
              crypto.
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - name: idempotency_key
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "201":
          description: Resource created successfully.
          content:
            application/json:
              example:
                asset: USDC
                created_at: 2026-05-01T10:00:00Z
                crypto_routing:
                  asset: USDC
                  destination:
                    address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                    memo: null
                  label: My ETH wallet
                  network: ethereum
                fiat_routing: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                label: My ETH wallet
                rail_class: crypto
                scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                status: active
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - rail_class
                  - status
                  - scope_ref
                  - created_at
                  - updated_at
                type: object
                additionalProperties: false
                properties:
                  asset:
                    anyOf:
                      - description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      - type: "null"
                  created_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                  crypto_routing:
                    anyOf:
                      - required:
                          - asset
                          - network
                          - destination
                          - label
                        type: object
                        additionalProperties: false
                        properties:
                          asset:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          destination:
                            required:
                              - address
                              - memo
                            type: object
                            additionalProperties: false
                            properties:
                              address:
                                type: string
                                minLength: 1
                                maxLength: 256
                              memo:
                                anyOf:
                                  - type: string
                                  - type: "null"
                          label:
                            anyOf:
                              - type: string
                              - type: "null"
                          network:
                            type: string
                            minLength: 1
                      - type: "null"
                  fiat_routing:
                    anyOf:
                      - required:
                          - fiat_rail
                          - method
                          - currency
                          - beneficiary_name
                          - bank_coordinates
                          - reference_hint
                        type: object
                        additionalProperties: false
                        properties:
                          bank_coordinates:
                            oneOf:
                              - required:
                                  - scheme
                                  - iban
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  iban:
                                    type: string
                                    minLength: 1
                                    maxLength: 34
                                  scheme:
                                    type: string
                                    const: iban
                              - required:
                                  - scheme
                                  - account_number
                                  - routing_codes
                                  - bic
                                  - account_holder_name
                                  - bank_name
                                  - country
                                type: object
                                additionalProperties: false
                                properties:
                                  account_holder_name:
                                    type: string
                                    minLength: 1
                                    maxLength: 140
                                  account_number:
                                    type: string
                                    minLength: 1
                                    maxLength: 64
                                  account_type:
                                    description: Checking or savings. Required by some payout rails (a US domestic
                                      wire); null or absent where the rail has
                                      no such concept.
                                    anyOf:
                                      - type: string
                                        enum:
                                          - checking
                                          - savings
                                      - type: "null"
                                  bank_address:
                                    description: Postal address of the bank that holds the account.
                                    anyOf:
                                      - required:
                                          - lines
                                          - city
                                          - region
                                          - postal_code
                                          - country
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          city:
                                            type: string
                                            minLength: 1
                                            maxLength: 140
                                          country:
                                            type: string
                                            pattern: ^[A-Z]{2}$
                                          lines:
                                            type: array
                                            items:
                                              type: string
                                              minLength: 1
                                              maxLength: 140
                                            maxItems: 4
                                            minItems: 1
                                          postal_code:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 32
                                              - type: "null"
                                          region:
                                            anyOf:
                                              - type: string
                                                minLength: 1
                                                maxLength: 140
                                              - type: "null"
                                      - type: "null"
                                  bank_name:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 140
                                      - type: "null"
                                  bic:
                                    anyOf:
                                      - type: string
                                        minLength: 1
                                        maxLength: 11
                                      - type: "null"
                                  country:
                                    type: string
                                    pattern: ^[A-Z]{2}$
                                  routing_codes:
                                    type: array
                                    items:
                                      required:
                                        - type
                                        - value
                                      type: object
                                      additionalProperties: false
                                      properties:
                                        type:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                        value:
                                          type: string
                                          minLength: 1
                                          maxLength: 64
                                    maxItems: 16
                                    minItems: 1
                                  scheme:
                                    type: string
                                    const: local_account
                          beneficiary_name:
                            type: string
                            minLength: 1
                            maxLength: 140
                          currency:
                            description: Currency code (ISO-4217 or on-chain ticker)
                            type: string
                            pattern: ^[A-Z0-9]{1,16}$
                          fiat_rail:
                            type: string
                            enum:
                              - sepa_credit_transfer
                              - faster_payments
                              - swift
                              - local_bank_transfer
                              - fedwire
                          method:
                            type: string
                            enum:
                              - bank_transfer
                          reference_hint:
                            anyOf:
                              - type: string
                                minLength: 1
                                maxLength: 140
                              - type: "null"
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  label:
                    anyOf:
                      - type: string
                      - type: "null"
                  rail_class:
                    type: string
                    enum:
                      - fiat
                      - crypto
                  scope_ref:
                    type: string
                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  status:
                    type: string
                    enum:
                      - active
                      - disabled
                      - retired
                  updated_at:
                    type: string
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                    format: date-time
                examples:
                  - asset: USDC
                    created_at: 2026-05-01T10:00:00Z
                    crypto_routing:
                      asset: USDC
                      destination:
                        address: "0xAbCd1234567890AbCd1234567890AbCd12345678"
                        memo: null
                      label: My ETH wallet
                      network: ethereum
                    fiat_routing: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    label: My ETH wallet
                    rail_class: crypto
                    scope_ref: clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    status: active
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawal_destinations.retire
      x-required-capability:
        - withdrawal_destinations.manage
  /withdrawals:
    get:
      summary: List withdrawals
      tags:
        - Live Operations
        - Withdrawals
      security:
        - BearerAuth: []
      parameters:
        - name: account_ref
          in: query
          required: false
          schema:
            type: string
            pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/PageToken"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                items:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    dispatch_attempt_id: null
                    failure_reason: null
                    family: withdrawal
                    family_flow_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fee_transaction_ids: []
                    fill_rate: null
                    hold_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    network: ethereum
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    principal_transaction_id: null
                    rail: ethereum
                    rail_class: crypto
                    release_transaction_id: null
                    settled_at: null
                    settlement_evidence: null
                    status: executing
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                    withdrawal_attempt_id: null
                next_page_token: null
              schema:
                required:
                  - items
                  - next_page_token
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      required:
                        - id
                        - family
                        - status
                        - account_ref
                        - principal_amount
                        - fee_summary
                        - fill_rate
                        - failure_reason
                        - settled_at
                        - approval_ref
                        - subject_attribution
                        - created_at
                        - updated_at
                        - family_flow_id
                        - leg_attempt_id
                        - withdrawal_attempt_id
                        - hold_id
                        - dispatch_attempt_id
                        - destination_id
                        - rail_class
                        - rail
                        - network
                        - settlement_evidence
                        - principal_transaction_id
                        - fee_transaction_ids
                        - release_transaction_id
                      type: object
                      additionalProperties: false
                      properties:
                        account_ref:
                          type: string
                          pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                        approval_ref:
                          anyOf:
                            - required:
                                - approval_id
                                - reason_code
                                - expires_at
                              type: object
                              additionalProperties: false
                              properties:
                                approval_id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                expires_at:
                                  anyOf:
                                    - type: string
                                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                      format: date-time
                                    - type: string
                                      format: date-time
                                reason_code:
                                  anyOf:
                                    - type: string
                                    - type: "null"
                            - type: "null"
                        compliance_assessment_ref:
                          anyOf:
                            - type: string
                              pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                            - type: "null"
                        created_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        destination_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        dispatch_attempt_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        failure_reason:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        family:
                          type: string
                          const: withdrawal
                        family_flow_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        fee_summary:
                          anyOf:
                            - required:
                                - components
                                - total
                              type: object
                              additionalProperties: false
                              properties:
                                components:
                                  type: array
                                  items:
                                    required:
                                      - kind
                                      - amount
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      amount:
                                        required:
                                          - value
                                          - currency
                                        type: object
                                        additionalProperties: false
                                        properties:
                                          currency:
                                            description: Currency code (ISO-4217 or on-chain ticker)
                                            type: string
                                            pattern: ^[A-Z0-9]{1,16}$
                                          value:
                                            description: DecimalString
                                            type: string
                                            pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                      kind:
                                        type: string
                                        enum:
                                          - platform_fee
                                          - enterprise_fee
                                          - network_fee
                                          - spread
                                total:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                            - type: "null"
                        fee_transaction_ids:
                          anyOf:
                            - type: array
                              items:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                            - type: "null"
                        fill_rate:
                          anyOf:
                            - type: string
                            - type: "null"
                        hold_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        id:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                        leg_attempt_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        network:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        principal_amount:
                          required:
                            - value
                            - currency
                          type: object
                          additionalProperties: false
                          properties:
                            currency:
                              description: Currency code (ISO-4217 or on-chain ticker)
                              type: string
                              pattern: ^[A-Z0-9]{1,16}$
                            value:
                              description: DecimalString
                              type: string
                              pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                        principal_transaction_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        rail:
                          anyOf:
                            - type: string
                              minLength: 1
                            - type: "null"
                        rail_class:
                          anyOf:
                            - type: string
                              enum:
                                - fiat
                                - crypto
                            - type: "null"
                        release_transaction_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                        settled_at:
                          anyOf:
                            - anyOf:
                                - type: string
                                  pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                  format: date-time
                                - type: string
                                  format: date-time
                            - type: "null"
                        settlement_evidence:
                          anyOf:
                            - oneOf:
                                - required:
                                    - kind
                                    - network
                                    - transaction_hash
                                    - block_number
                                    - confirmations
                                    - finalized_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    block_number:
                                      anyOf:
                                        - type: integer
                                          minimum: 0
                                          maximum: 9007199254740991
                                        - type: "null"
                                    confirmations:
                                      anyOf:
                                        - type: integer
                                          minimum: 0
                                          maximum: 9007199254740991
                                        - type: "null"
                                    finalized_at:
                                      anyOf:
                                        - anyOf:
                                            - type: string
                                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                              format: date-time
                                            - type: string
                                              format: date-time
                                        - type: "null"
                                    kind:
                                      type: string
                                      const: blockchain_transaction
                                    network:
                                      type: string
                                      minLength: 1
                                    transaction_hash:
                                      type: string
                                      minLength: 1
                                - required:
                                    - kind
                                    - fiat_rail
                                    - rail_reference
                                    - settled_at
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    fiat_rail:
                                      type: string
                                      minLength: 1
                                    kind:
                                      type: string
                                      const: bank_transfer
                                    rail_reference:
                                      anyOf:
                                        - type: string
                                          minLength: 1
                                        - type: "null"
                                    settled_at:
                                      anyOf:
                                        - anyOf:
                                            - type: string
                                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                              format: date-time
                                            - type: string
                                              format: date-time
                                        - type: "null"
                            - type: "null"
                        status:
                          type: string
                          enum:
                            - requested
                            - admissible
                            - executing
                            - pending_approval
                            - pending_admission
                            - pending_compliance
                            - executed
                            - settled
                            - ledger_visible
                            - failed
                            - cancelled
                            - partially_settled
                        subject_attribution:
                          required:
                            - authenticated_principal
                            - subject
                            - actor
                            - initiated_by
                            - approved_by
                            - identity_source
                            - federation
                            - enterprise_binding
                          type: object
                          additionalProperties: false
                          properties:
                            actor:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            approved_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            authenticated_principal:
                              required:
                                - id
                                - kind
                              type: object
                              additionalProperties: false
                              properties:
                                id:
                                  type: string
                                  pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                  format: uuid
                                kind:
                                  type: string
                                  enum:
                                    - user
                                    - service
                                    - system
                                tenant_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            enterprise_binding:
                              required:
                                - topology_ref
                                - tenant_type
                              type: object
                              additionalProperties: false
                              properties:
                                tenant_type:
                                  type: string
                                  enum:
                                    - enterprise
                                    - platform_operator
                                topology_ref:
                                  anyOf:
                                    - type: string
                                      pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                    - type: "null"
                            federation:
                              anyOf:
                                - required:
                                    - issuer
                                    - external_subject
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    external_subject:
                                      type: string
                                      minLength: 1
                                    issuer:
                                      type: string
                                      minLength: 1
                                - type: "null"
                            identity_source:
                              type: string
                              enum:
                                - platform-managed
                                - federated
                                - system
                            initiated_by:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                            subject:
                              anyOf:
                                - required:
                                    - id
                                    - kind
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                      format: uuid
                                    kind:
                                      type: string
                                      enum:
                                        - user
                                        - service
                                        - system
                                    tenant_ref:
                                      anyOf:
                                        - type: string
                                          pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                        - type: "null"
                                - type: "null"
                        updated_at:
                          anyOf:
                            - type: string
                              pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                              format: date-time
                            - type: string
                              format: date-time
                        withdrawal_attempt_id:
                          anyOf:
                            - type: string
                              pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                              format: uuid
                            - type: "null"
                  next_page_token:
                    anyOf:
                      - type: string
                      - type: "null"
                examples:
                  - items:
                      - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        approval_ref: null
                        created_at: 2026-05-01T10:00:00Z
                        destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        dispatch_attempt_id: null
                        failure_reason: null
                        family: withdrawal
                        family_flow_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        fee_summary:
                          components:
                            - amount:
                                currency: USDC
                                value: "1.00"
                              kind: network_fee
                          total:
                            currency: USDC
                            value: "1.00"
                        fee_transaction_ids: []
                        fill_rate: null
                        hold_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        network: ethereum
                        principal_amount:
                          currency: USDC
                          value: "250.00"
                        principal_transaction_id: null
                        rail: ethereum
                        rail_class: crypto
                        release_transaction_id: null
                        settled_at: null
                        settlement_evidence: null
                        status: executing
                        subject_attribution:
                          actor: null
                          approved_by: null
                          authenticated_principal:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          enterprise_binding:
                            tenant_type: enterprise
                            topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                          federation: null
                          identity_source: platform-managed
                          initiated_by: null
                          subject:
                            id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                            kind: user
                            tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        updated_at: 2026-05-01T10:00:00Z
                        withdrawal_attempt_id: null
                    next_page_token: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawals.list
      x-required-capability:
        - withdrawals.read
    post:
      description: Creates a withdrawal operation. For crypto requests, bind either a
        stored withdrawal destination (`destination_id`) or a one-time inline
        `destination` (`{address, memo}` plus `network`) — exactly one crypto
        destination path must be present. For fiat requests, bind a stored fiat
        withdrawal destination by its `withdrawal_destination_id`, resolved
        within the supplied `account_ref` scope; the canonical bank routing and
        the authoritative owner topology are sourced from the stored
        destination, never from the request body. Both rails are subject to
        operation admission checks; fiat dispatch also depends on the
        availability and runtime readiness of the selected fiat rail. A fiat
        `amount` with more fractional digits than the catalog scale of its
        currency is refused with `400 invalid_request` and `data.reason =
        amount_scale_exceeded` before anything is held; trailing zeros do not
        count (`100.000` is `100`), and a currency the catalog has no scale for
        is not checked. Successful responses return the operation snapshot — for
        an immediately admitted withdrawal the response may carry `status =
        "executing"` once operation-flow has written that state. Idempotent on
        `Idempotency-Key` or `client_idempotency_key`. Human callers must obtain
        a step-up confirmation via `POST /action-tokens` and submit it in the
        `X-Action-Token` header; service principals are exempt.
      summary: Create withdrawal
      tags:
        - Live Operations
        - Withdrawals
      security:
        - BearerAuth: []
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
        - $ref: "#/components/parameters/XActionToken"
      requestBody:
        required: true
        content:
          application/json:
            example:
              account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              amount:
                currency: EUR
                value: "100.00"
              rail: fiat
              withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
            schema:
              examples:
                - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  amount:
                    currency: EUR
                    value: "100.00"
                  rail: fiat
                  withdrawal_destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
              oneOf:
                - required:
                    - amount
                    - account_ref
                    - rail
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    amount:
                      required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    client_idempotency_key:
                      type: string
                      minLength: 1
                    destination:
                      required:
                        - address
                        - memo
                      type: object
                      additionalProperties: false
                      properties:
                        address:
                          type: string
                          minLength: 1
                          maxLength: 256
                        memo:
                          anyOf:
                            - type: string
                            - type: "null"
                    destination_id:
                      type: string
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      format: uuid
                    network:
                      type: string
                      minLength: 1
                    rail:
                      type: string
                      const: crypto
                - required:
                    - amount
                    - account_ref
                    - withdrawal_destination_id
                    - rail
                  type: object
                  additionalProperties: false
                  properties:
                    account_ref:
                      type: string
                      pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                    amount:
                      required:
                        - value
                        - currency
                      type: object
                      additionalProperties: false
                      properties:
                        currency:
                          description: Currency code (ISO-4217 or on-chain ticker)
                          type: string
                          pattern: ^[A-Z0-9]{1,16}$
                        value:
                          description: DecimalString
                          type: string
                          pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                    client_idempotency_key:
                      type: string
                      minLength: 1
                    rail:
                      type: string
                      const: fiat
                    withdrawal_destination_id:
                      type: string
                      pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                      format: uuid
      responses:
        "202":
          description: Request accepted for asynchronous processing. Follow the resource
            identifiers returned by this operation to observe progress.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: withdrawal
                family_params: {}
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: network_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: executing
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: withdrawal
                    family_params: {}
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: executing
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeActionTokenRequired"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "422":
          $ref: "#/components/responses/EdgeNotAdmissible"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawals.create
      x-required-capability:
        - withdrawals.create
  /withdrawals/{withdrawal_id}:
    get:
      summary: Get withdrawal
      tags:
        - Live Operations
        - Withdrawals
      security:
        - BearerAuth: []
      parameters:
        - name: withdrawal_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                dispatch_attempt_id: null
                failure_reason: null
                family: withdrawal
                family_flow_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                fee_summary:
                  components:
                    - amount:
                        currency: USDC
                        value: "1.00"
                      kind: network_fee
                  total:
                    currency: USDC
                    value: "1.00"
                fee_transaction_ids: []
                fill_rate: null
                hold_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                network: ethereum
                principal_amount:
                  currency: USDC
                  value: "250.00"
                principal_transaction_id: null
                rail: ethereum
                rail_class: crypto
                release_transaction_id: null
                settled_at: null
                settlement_evidence: null
                status: executing
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
                withdrawal_attempt_id: null
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_flow_id
                  - leg_attempt_id
                  - withdrawal_attempt_id
                  - hold_id
                  - dispatch_attempt_id
                  - destination_id
                  - rail_class
                  - rail
                  - network
                  - settlement_evidence
                  - principal_transaction_id
                  - fee_transaction_ids
                  - release_transaction_id
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  destination_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  dispatch_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    const: withdrawal
                  family_flow_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fee_transaction_ids:
                    anyOf:
                      - type: array
                        items:
                          type: string
                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                          format: uuid
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  hold_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  leg_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  network:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  principal_transaction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  rail:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  rail_class:
                    anyOf:
                      - type: string
                        enum:
                          - fiat
                          - crypto
                      - type: "null"
                  release_transaction_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  settlement_evidence:
                    anyOf:
                      - oneOf:
                          - required:
                              - kind
                              - network
                              - transaction_hash
                              - block_number
                              - confirmations
                              - finalized_at
                            type: object
                            additionalProperties: false
                            properties:
                              block_number:
                                anyOf:
                                  - type: integer
                                    minimum: 0
                                    maximum: 9007199254740991
                                  - type: "null"
                              confirmations:
                                anyOf:
                                  - type: integer
                                    minimum: 0
                                    maximum: 9007199254740991
                                  - type: "null"
                              finalized_at:
                                anyOf:
                                  - anyOf:
                                      - type: string
                                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                        format: date-time
                                      - type: string
                                        format: date-time
                                  - type: "null"
                              kind:
                                type: string
                                const: blockchain_transaction
                              network:
                                type: string
                                minLength: 1
                              transaction_hash:
                                type: string
                                minLength: 1
                          - required:
                              - kind
                              - fiat_rail
                              - rail_reference
                              - settled_at
                            type: object
                            additionalProperties: false
                            properties:
                              fiat_rail:
                                type: string
                                minLength: 1
                              kind:
                                type: string
                                const: bank_transfer
                              rail_reference:
                                anyOf:
                                  - type: string
                                    minLength: 1
                                  - type: "null"
                              settled_at:
                                anyOf:
                                  - anyOf:
                                      - type: string
                                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                        format: date-time
                                      - type: string
                                        format: date-time
                                  - type: "null"
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  withdrawal_attempt_id:
                    anyOf:
                      - type: string
                        pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        format: uuid
                      - type: "null"
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    destination_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    dispatch_attempt_id: null
                    failure_reason: null
                    family: withdrawal
                    family_flow_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    fee_summary:
                      components:
                        - amount:
                            currency: USDC
                            value: "1.00"
                          kind: network_fee
                      total:
                        currency: USDC
                        value: "1.00"
                    fee_transaction_ids: []
                    fill_rate: null
                    hold_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    leg_attempt_id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    network: ethereum
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    principal_transaction_id: null
                    rail: ethereum
                    rail_class: crypto
                    release_transaction_id: null
                    settled_at: null
                    settlement_evidence: null
                    status: executing
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
                    withdrawal_attempt_id: null
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawals.get
      x-required-capability:
        - withdrawals.read
  /withdrawals/{withdrawal_id}/cancel:
    post:
      description: Cancels a withdrawal while it is waiting for approval or
        compliance, before dispatch. Returns the refreshed operation with status
        `cancelled`. A withdrawal that has already started execution cannot be
        cancelled and returns `409 state_conflict` with `data.reason =
        operation_not_cancellable`.
      summary: Cancel withdrawal
      tags:
        - Live Operations
        - Withdrawals
      security:
        - BearerAuth: []
      parameters:
        - name: withdrawal_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Operation succeeded.
          content:
            application/json:
              example:
                account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                approval_ref: null
                created_at: 2026-05-01T10:00:00Z
                failure_reason: null
                family: withdrawal
                family_params: {}
                fee_summary: null
                fill_rate: null
                id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                principal_amount:
                  currency: USDC
                  value: "250.00"
                settled_at: null
                status: cancelled
                subject_attribution:
                  actor: null
                  approved_by: null
                  authenticated_principal:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  enterprise_binding:
                    tenant_type: enterprise
                    topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                  federation: null
                  identity_source: platform-managed
                  initiated_by: null
                  subject:
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    kind: user
                    tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                updated_at: 2026-05-01T10:00:00Z
              schema:
                required:
                  - id
                  - family
                  - status
                  - account_ref
                  - principal_amount
                  - fee_summary
                  - fill_rate
                  - failure_reason
                  - settled_at
                  - approval_ref
                  - subject_attribution
                  - created_at
                  - updated_at
                  - family_params
                type: object
                additionalProperties: false
                properties:
                  account_ref:
                    type: string
                    pattern: ^(master-accounts|client-accounts)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                  admission_hold_reason:
                    anyOf:
                      - type: string
                        enum:
                          - CLIENT_NOT_VERIFIED
                          - ENTERPRISE_NOT_VERIFIED
                          - ENTERPRISE_NOT_OPERATIONAL
                          - ENTERPRISE_RESTRICTED
                          - ACCOUNT_SUSPENDED
                          - ACCOUNT_CLOSED
                          - CLIENT_SUSPENDED
                          - CLIENT_CLOSED
                      - type: "null"
                  approval_ref:
                    anyOf:
                      - required:
                          - approval_id
                          - reason_code
                          - expires_at
                        type: object
                        additionalProperties: false
                        properties:
                          approval_id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          expires_at:
                            anyOf:
                              - type: string
                                pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                                format: date-time
                              - type: string
                                format: date-time
                          reason_code:
                            anyOf:
                              - type: string
                              - type: "null"
                      - type: "null"
                  compliance_assessment_ref:
                    anyOf:
                      - type: string
                        pattern: ^(compliance-assessments)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                      - type: "null"
                  created_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                  failure_reason:
                    anyOf:
                      - type: string
                        minLength: 1
                      - type: "null"
                  family:
                    type: string
                    enum:
                      - deposit
                      - withdrawal
                      - conversion
                      - external_settlement_conversion
                      - internal_transfer
                      - on_ramp
                      - off_ramp
                      - loan_origination
                      - loan_repayment
                      - loan_liquidation
                      - loan_closing
                      - loan_extension
                  family_params:
                    type: object
                    additionalProperties: {}
                    propertyNames:
                      type: string
                  fee_summary:
                    anyOf:
                      - required:
                          - components
                          - total
                        type: object
                        additionalProperties: false
                        properties:
                          components:
                            type: array
                            items:
                              required:
                                - kind
                                - amount
                              type: object
                              additionalProperties: false
                              properties:
                                amount:
                                  required:
                                    - value
                                    - currency
                                  type: object
                                  additionalProperties: false
                                  properties:
                                    currency:
                                      description: Currency code (ISO-4217 or on-chain ticker)
                                      type: string
                                      pattern: ^[A-Z0-9]{1,16}$
                                    value:
                                      description: DecimalString
                                      type: string
                                      pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                                kind:
                                  type: string
                                  enum:
                                    - platform_fee
                                    - enterprise_fee
                                    - network_fee
                                    - spread
                          total:
                            required:
                              - value
                              - currency
                            type: object
                            additionalProperties: false
                            properties:
                              currency:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              value:
                                description: DecimalString
                                type: string
                                pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                      - type: "null"
                  fill_rate:
                    anyOf:
                      - type: string
                      - type: "null"
                  id:
                    type: string
                    pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    format: uuid
                  principal_amount:
                    required:
                      - value
                      - currency
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        description: Currency code (ISO-4217 or on-chain ticker)
                        type: string
                        pattern: ^[A-Z0-9]{1,16}$
                      value:
                        description: DecimalString
                        type: string
                        pattern: ^(0|[1-9][0-9]{0,29})(\.[0-9]{1,18})?$
                  settled_at:
                    anyOf:
                      - anyOf:
                          - type: string
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                            format: date-time
                          - type: string
                            format: date-time
                      - type: "null"
                  status:
                    type: string
                    enum:
                      - requested
                      - admissible
                      - executing
                      - pending_approval
                      - pending_admission
                      - pending_compliance
                      - executed
                      - settled
                      - ledger_visible
                      - failed
                      - cancelled
                      - partially_settled
                  subject_attribution:
                    required:
                      - authenticated_principal
                      - subject
                      - actor
                      - initiated_by
                      - approved_by
                      - identity_source
                      - federation
                      - enterprise_binding
                    type: object
                    additionalProperties: false
                    properties:
                      actor:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      approved_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      authenticated_principal:
                        required:
                          - id
                          - kind
                        type: object
                        additionalProperties: false
                        properties:
                          id:
                            type: string
                            pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                            format: uuid
                          kind:
                            type: string
                            enum:
                              - user
                              - service
                              - system
                          tenant_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      enterprise_binding:
                        required:
                          - topology_ref
                          - tenant_type
                        type: object
                        additionalProperties: false
                        properties:
                          tenant_type:
                            type: string
                            enum:
                              - enterprise
                              - platform_operator
                          topology_ref:
                            anyOf:
                              - type: string
                                pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                              - type: "null"
                      federation:
                        anyOf:
                          - required:
                              - issuer
                              - external_subject
                            type: object
                            additionalProperties: false
                            properties:
                              external_subject:
                                type: string
                                minLength: 1
                              issuer:
                                type: string
                                minLength: 1
                          - type: "null"
                      identity_source:
                        type: string
                        enum:
                          - platform-managed
                          - federated
                          - system
                      initiated_by:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                      subject:
                        anyOf:
                          - required:
                              - id
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              id:
                                type: string
                                pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                                format: uuid
                              kind:
                                type: string
                                enum:
                                  - user
                                  - service
                                  - system
                              tenant_ref:
                                anyOf:
                                  - type: string
                                    pattern: ^(enterprises|platform-operators|clients)\/([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
                                  - type: "null"
                          - type: "null"
                  updated_at:
                    anyOf:
                      - type: string
                        pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
                        format: date-time
                      - type: string
                        format: date-time
                examples:
                  - account_ref: client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    approval_ref: null
                    created_at: 2026-05-01T10:00:00Z
                    failure_reason: null
                    family: withdrawal
                    family_params: {}
                    fee_summary: null
                    fill_rate: null
                    id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    principal_amount:
                      currency: USDC
                      value: "250.00"
                    settled_at: null
                    status: cancelled
                    subject_attribution:
                      actor: null
                      approved_by: null
                      authenticated_principal:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      enterprise_binding:
                        tenant_type: enterprise
                        topology_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                      federation: null
                      identity_source: platform-managed
                      initiated_by: null
                      subject:
                        id: b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                        kind: user
                        tenant_ref: enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b
                    updated_at: 2026-05-01T10:00:00Z
        "400":
          $ref: "#/components/responses/EdgeBadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/EdgeForbidden"
        "404":
          $ref: "#/components/responses/EdgeNotFound"
        "409":
          $ref: "#/components/responses/EdgeConflict"
        "500":
          $ref: "#/components/responses/EdgeInternalServerError"
        "502":
          $ref: "#/components/responses/EdgeBadGateway"
        "503":
          $ref: "#/components/responses/TemporarilyUnavailable"
      operationId: withdrawals.cancel
      x-required-capability:
        - withdrawals.manage
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Client-generated key, 1-128 characters. Accepted on POST requests
        and required where marked. For the same concrete path and
        caller/subject/tenant scope, an identical body replays the original
        status and body; a different body returns 409 idempotency_conflict. Keep
        query parameters unchanged when retrying.
      schema:
        type: string
        minLength: 1
        maxLength: 128
    IfMatch:
      name: If-Match
      in: header
      required: true
      description: Weak entity tag from a prior GET. Mismatch causes the request to
        fail with 412 Precondition Failed.
      schema:
        type: string
        minLength: 1
    PageSize:
      name: page_size
      in: query
      required: false
      description: Cursor pagination page size. The canonical contract accepts
        integers from 1 to 500.
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    PageToken:
      name: page_token
      in: query
      required: false
      description: Opaque cursor returned by a previous page.
      schema:
        type: string
    XActionToken:
      name: X-Action-Token
      in: header
      required: false
      description: Single-use step-up confirmation token bound to the server-canonical
        command for this request. Required when the effective subject is a human
        user. Callers without a human subject skip only this confirmation check
        and still pass normal authentication and capability guards. Obtain the
        token through `POST /action-tokens`, then submit it with the guarded
        request. Structured commands are supported for withdrawal, conversion,
        and external-settlement conversion creation; the issue endpoint also
        accepts `command_digest`. Missing or invalid human-confirmation tokens
        produce `400` with `code` in {`action_token_required`,
        `action_token_rejected`}; an unreachable approval service produces `502
        action_token_validation_failed`.
      schema:
        type: string
        minLength: 1
  responses:
    EdgeActionTokenRequired:
      description: "Step-up confirmation failed for a money-movement operation. `code`
        is one of: `action_token_required` (X-Action-Token header missing),
        `action_token_rejected` (token is unknown, expired, already consumed, or
        its server-canonical command binding does not match the current
        request). Obtain a fresh token via `POST /action-tokens` and retry.
        Structured issuance accepts `withdrawal.create`, `conversion.create`,
        and `external_settlement_conversion.create`. The issue endpoint also
        accepts `command_digest`. Human confirmation applies to the effective
        user subject; callers without a human subject skip this confirmation
        check."
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeBadGateway:
      description: Upstream service returned an unexpected error.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                    nullable: true
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type: integer
                    minimum: 0
                    nullable: true
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeBadRequest:
      description: Invalid request payload, query, or parameter shape.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                    nullable: true
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type: integer
                    minimum: 0
                    nullable: true
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeConflict:
      description: State conflict — the request cannot be applied to the current
        resource state.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeForbidden:
      description: Caller lacks the required capability or permitted scope.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeGone:
      description: The endpoint has been retired and returns code deprecated_endpoint.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeInternalServerError:
      description: An unexpected internal failure occurred. The public error code is
        temporarily_unavailable; internal details are not exposed.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeNotAdmissible:
      description: The request cannot be processed under the resource or route
        contract. Depending on the endpoint, code can be not_admissible or
        unsupported_currency; inspect the documented code and data.reason.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgeNotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    EdgePreconditionFailed:
      description: If-Match check failed; the resource has changed since the cached etag.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    ForbiddenCapabilityScope:
      description: Caller is authenticated but lacks the capability or topology scope
        required for this operation.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    InsufficientUserAuthentication:
      description: Additional user authentication is required. The response includes
        `code = insufficient_user_authentication`; the `WWW-Authenticate` header
        carries RFC 9470 `acr_values` and `max_age` parameters that tell the
        client which step-up assurance to request before retrying.
      content:
        application/json:
          schema:
            required:
              - code
              - message
              - data
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
                const: insufficient_user_authentication
              data:
                required:
                  - acr_values
                  - max_age
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    type: string
                  max_age:
                    type: string
              message:
                type: string
      headers:
        WWW-Authenticate:
          description: RFC 9470 challenge. `acr_values` is `urn:yh:acr:mfa` for mandatory
            MFA policy and `urn:yh:acr:mfa-if-enrolled` for optional
            critical-step-up policy.
          example: Bearer error="insufficient_user_authentication",
            acr_values="urn:yh:acr:mfa", max_age="300"
          schema:
            type: string
    RateLimited:
      description: The request was rate limited; retry according to the returned
        backoff information.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    TemporarilyUnavailable:
      description: Service is temporarily unavailable; retry with backoff.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                    nullable: true
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type: integer
                    minimum: 0
                    nullable: true
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
    Unauthorized:
      description: Caller is not authenticated or the bearer token is invalid.
      content:
        application/json:
          schema:
            required:
              - code
              - message
            type: object
            additionalProperties: false
            properties:
              code:
                type: string
              data:
                type: object
                additionalProperties: false
                properties:
                  acr_values:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  blockers:
                    description: "For `closure_preconditions_not_met` on a terminal lifecycle verb:
                      what must be resolved before the transition."
                    type: array
                    items:
                      required:
                        - type
                        - description
                      type: object
                      additionalProperties: false
                      properties:
                        description:
                          type: string
                        type:
                          type: string
                          enum:
                            - non_zero_balance
                            - active_sub_resources
                            - pending_operations
                            - active_users
                            - active_service_accounts
                            - active_role_assignments
                        assets:
                          type: array
                          items:
                            required:
                              - asset
                              - kind
                            type: object
                            additionalProperties: false
                            properties:
                              asset:
                                description: Currency code (ISO-4217 or on-chain ticker)
                                type: string
                                pattern: ^[A-Z0-9]{1,16}$
                              kind:
                                type: string
                                enum:
                                  - balance
                                  - held
                                  - owed
                                  - unsettled
                          minItems: 1
                        count:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                  code:
                    description: "For legal refusals: the document code the refusal is about."
                    type: string
                  max_age:
                    description: RFC 9470 step-up challenge (`insufficient_user_authentication`).
                    type: string
                  max_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the product
                      maximum in source asset units; null means no maximum."
                    type:
                      - object
                      - "null"
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  min_source_amount:
                    required:
                      - value
                      - currency
                    description: "For `amount_below_minimum` / `amount_above_maximum`: the effective
                      minimum in source asset units, fees included."
                    type: object
                    additionalProperties: false
                    properties:
                      currency:
                        type: string
                      value:
                        type: string
                  published_version:
                    description: "For `document_version_superseded`: the version currently
                      published."
                    type: string
                  reason:
                    description: Typed refinement of `code`, from the failing service's contract.
                    type: string
                  resource:
                    description: Resource kind a `resource_not_found` refers to.
                    type: string
                  retry_after_ms:
                    description: Suggested back-off in milliseconds for throttling or temporary
                      unavailability; null means no delay is known.
                    type:
                      - integer
                      - "null"
                    minimum: 0
                  source:
                    description: "For `not_admissible`: the gate that denied (verification,
                      lifecycle, policy, compliance)."
                    type: string
              details:
                type: object
                additionalProperties: true
              message:
                type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT used to authorize calls to tenant-facing API endpoints.
    OAuth2ClientCredentials:
      type: oauth2
      description: OAuth 2.0 token acquisition using POST /oauth/token. Service
        accounts use the client_credentials grant. Token exchange is also
        available at the same token endpoint for federated human access flows.
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes: {}
x-tagGroups:
  - name: Workflow
    tags:
      - Activation
      - Setup
      - Distribution
      - Live Operations
      - Settlement
      - Suspension
  - name: Reference
    tags:
      - Auth
      - Me
      - Enterprises
      - Master Accounts
      - Commercial Agreements
      - Clients
      - Client Accounts
      - Users
      - Service Accounts
      - Roles
      - Role Assignments
      - Identity Providers
      - Capabilities
      - Policies
      - Action Tokens
      - Approvals
      - Balances
      - Deposits
      - Deposit Instructions
      - Funding Endpoints
      - Payment Methods
      - Payout Methods
      - Crypto Networks
      - Conversion Pairs
      - Webhook Subscriptions
      - Events
      - Withdrawals
      - Withdrawal Destinations
      - Internal Transfers
      - Conversions
      - External Settlement Conversions
      - Fee Previews
      - Prices
      - User Invitations
      - On-ramp Sessions
      - Off-ramp Sessions
      - Operations Activity Exports
      - User Action Audit Entries
      - User Action Audit Exports
      - Audit
      - Reporting
      - Sandbox
