platform-admin-openapi.yaml

openapi: 3.0.4
info:
  title: Sphereon Platform Admin API
  version: 0.1.0
  x-products: [edk, vdx]
  description: |
    API for administering a Sphereon deployment.

    The application tenant uses this API to install and verify the platform
    license, choose the secret backend, set onboarding policy and read the
    evaluated onboarding availability, register and manage tenants and their
    domains, public endpoints and hierarchy, run the self-service signup
    lifecycle, configure each tenant's external identity providers, and complete
    owner onboarding. The application tenant is always authenticated through the
    platform's own hosted identity provider, so operators can always reach this
    surface, including before any customer tenant exists.

    ## Authentication and tenant context

    Every authenticated operation expects a bearer JWT. Tenant context is
    resolved from that token; it is never taken from a request parameter. The
    self-service signup request, the signup email confirmation, and the owner
    invitation redemption are the public, unauthenticated entry points.

    ## Secret handling

    Secrets are write-only on the way in and are never echoed. The license token,
    identity provider client secret, signup verification token, domain
    verification token, and owner invitation token and credential are accepted
    only on request bodies. Responses expose secrets only by opaque reference,
    for example `clientSecretRef` and `configRef`.

    ## License gating

    Two capability groups are license-gated. The self-service signup operations
    function only when the tenant signup entitlement is licensed, and the tenant
    federation operations function only when the tenant federation entitlement is
    licensed. Each such operation carries an `x-license-protection` descriptor.

    ## Error format

    Errors are returned as the `{ "error": { "code", "message", "details"? } }`
    envelope. A correlation identifier is available on every response.
  contact:
    name: Sphereon International B.V.
    email: support@sphereon.com
    url: https://sphereon.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.example.com/api/platform/admin/v1
    description: Production server.
  - url: http://localhost:8080/api/platform/admin/v1
    description: Local development server.
security:
  - bearer: []
tags:
  - name: PlatformAdmin
    description: Application-tenant bootstrap and status, license, secret backend, and onboarding policy and availability.
  - name: Tenants
    description: Tenant lifecycle, domains, public endpoints, hierarchy, and onboarding status.
  - name: TenantSignup
    description: Public self-service signup and its operator-side approval lifecycle.
  - name: TenantFederation
    description: Tenant-owned external identity providers.
  - name: OwnerBootstrap
    description: Public owner invitation redemption.
paths:
  # =====================================================================
  # PlatformAdmin
  # =====================================================================
  /application/tenant:
    get:
      tags: [PlatformAdmin]
      summary: Get application tenant status
      description: |
        Returns the runtime state of the application tenant, including the
        readiness of the platform-hosted authorization server and whether the
        first customer tenant can yet be registered.
      operationId: getApplicationTenant
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      responses:
        '200':
          description: Application tenant state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationTenantStatus'
              example:
                tenantId: application
                status: ACTIVE
                hostedAs:
                  required: true
                  available: true
                  issuerUrl: https://auth.platform.example
                canRegisterFirstRealTenant: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /application/tenant/bootstrap:
    post:
      tags: [PlatformAdmin]
      summary: Create or reconcile the application tenant
      description: |
        Creates the application tenant and its hosted authorization server, or
        reconciles them if they already exist, and returns the resulting state.
        Optional operator contact details seed the initial operator account.
      operationId: bootstrapApplicationTenant
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationTenantBootstrapRequest'
            example:
              operatorEmail: admin@acme.example
              operatorDisplayName: Acme Administrator
      responses:
        '200':
          description: Application tenant bootstrap or reconcile result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationTenantStatus'
              example:
                tenantId: application
                status: ACTIVE
                hostedAs:
                  required: true
                  available: true
                  issuerUrl: https://auth.platform.example
                canRegisterFirstRealTenant: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /application/license:
    get:
      tags: [PlatformAdmin]
      summary: Get the license status projection
      description: >
        Returns the sanitized status projection of the effective license -
        lifecycle status, per-product summaries, and expiry signals. The raw
        license token, decoded claims, and entitlement graph are never exposed.
      operationId: getApplicationLicense
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      responses:
        '200':
          description: License status projection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseStatusProjection'
              example:
                status: ACTIVE
                productSummaries:
                  - product: vdx
                    edition: enterprise
                    modules: [tenant, party, oid4vci]
                    quotaKeys: [max-root-tenants, max-total-tenants]
                customerId: cust-acme-001
                deploymentId: dep-eu-west-1
                issuer: Sphereon Licensing
                signingCertificateFingerprint: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                expiresAt: '2027-06-30T23:59:59Z'
                daysToExpiry: 386
                recoveryMode: false
                graceMode: false
                warnings: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags: [PlatformAdmin]
      summary: Install or replace the application license
      description: |
        Verifies and installs the supplied license token, replacing any active
        license, and returns the resulting license status projection. The license
        token is write-only and is never echoed.
      operationId: putApplicationLicense
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseActivationRequest'
            example:
              licenseToken: eyJhbGciOiJFZERTQSJ9.eyJ0aWVyIjoicHJvIn0.signature
      responses:
        '200':
          description: License status projection of the installed license.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseStatusProjection'
              example:
                status: ACTIVE
                productSummaries:
                  - product: vdx
                    edition: enterprise
                    modules: [tenant, party, oid4vci]
                    quotaKeys: [max-root-tenants, max-total-tenants]
                customerId: cust-acme-001
                deploymentId: dep-eu-west-1
                issuer: Sphereon Licensing
                signingCertificateFingerprint: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                expiresAt: '2027-06-30T23:59:59Z'
                daysToExpiry: 386
                recoveryMode: false
                graceMode: false
                warnings: []
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /application/license/verify:
    post:
      tags: [PlatformAdmin]
      summary: Verify a license token without installing it
      description: |
        Verifies the supplied license token and returns whether it is valid along
        with its sanitized status projection, without installing it. The license
        token is write-only and is never echoed.
      operationId: verifyApplicationLicense
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenseActivationRequest'
            example:
              licenseToken: eyJhbGciOiJFZERTQSJ9.eyJ0aWVyIjoicHJvIn0.signature
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseVerificationProjection'
              example:
                valid: true
                status:
                  status: ACTIVE
                  productSummaries:
                    - product: vdx
                      edition: enterprise
                      modules: [tenant, party, oid4vci]
                      quotaKeys: [max-root-tenants, max-total-tenants]
                  customerId: cust-acme-001
                  deploymentId: dep-eu-west-1
                  issuer: Sphereon Licensing
                  signingCertificateFingerprint: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                  expiresAt: '2027-06-30T23:59:59Z'
                  daysToExpiry: 386
                  recoveryMode: false
                  graceMode: false
                  warnings: []
                error: null
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /application/secrets/backend:
    get:
      tags: [PlatformAdmin]
      summary: Get configured secret backend
      description: Returns the configured secret backend and its opaque configuration reference. Plaintext secrets never appear here.
      operationId: getSecretBackend
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      responses:
        '200':
          description: Secret backend status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBackendStatus'
              example:
                configured: true
                backend: hashicorp-vault
                configRef: secret://platform/kv/tenant-secrets
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags: [PlatformAdmin]
      summary: Select the secret backend
      description: |
        Selects the secret backend that stores tenant and federation secrets and
        returns the resulting status. The optional `configRef` points at the
        resolved backend instance.
      operationId: putSecretBackend
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretBackendWrite'
            example:
              backend: hashicorp-vault
              configRef: secret://platform/kv/tenant-secrets
      responses:
        '200':
          description: Secret backend status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecretBackendStatus'
              example:
                configured: true
                backend: hashicorp-vault
                configRef: secret://platform/kv/tenant-secrets
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /application/onboarding:
    get:
      tags: [PlatformAdmin]
      summary: Get onboarding policy
      description: Returns the onboarding policy toggles that constrain which onboarding flows are accepted.
      operationId: getApplicationOnboarding
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      responses:
        '200':
          description: Onboarding policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingPolicy'
              example:
                rootTenantCreationEnabled: true
                adminInviteEnabled: true
                selfSignupEnabled: true
                subtenantSignupEnabled: false
                requireApprovalForSelfSignup: true
                updatedAt: '2026-06-08T09:15:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    put:
      tags: [PlatformAdmin]
      summary: Update onboarding policy
      description: |
        Updates the onboarding policy. Every field is optional; a field left
        unset leaves that toggle unchanged. Returns the full updated policy.
      operationId: putApplicationOnboarding
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnboardingPolicyWrite'
            example:
              selfSignupEnabled: true
              requireApprovalForSelfSignup: true
      responses:
        '200':
          description: Updated onboarding policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingPolicy'
              example:
                rootTenantCreationEnabled: true
                adminInviteEnabled: true
                selfSignupEnabled: true
                subtenantSignupEnabled: false
                requireApprovalForSelfSignup: true
                updatedAt: '2026-06-08T09:20:00Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /application/onboarding/availability:
    get:
      tags: [PlatformAdmin]
      summary: Get evaluated onboarding availability
      description: |
        Returns the evaluated availability matrix composed from license features,
        config toggles, and runtime readiness of the application tenant, email
        transport, and secret backend. Each flow carries a stable reason string
        when it is unavailable.
      operationId: getApplicationOnboardingAvailability
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      responses:
        '200':
          description: Evaluated onboarding availability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnboardingAvailability'
              example:
                applicationTenant:
                  enabled: true
                  hostedAsAvailable: true
                rootTenantCreation:
                  enabled: true
                  reason: null
                adminInvite:
                  enabled: true
                  reason: null
                selfSignup:
                  enabled: false
                  reason: config_disabled_self_signup
                subtenants:
                  enabled: true
                  reason: null
                email:
                  configured: true
                  healthy: true
                secretBackend:
                  configured: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # =====================================================================
  # Tenants
  # =====================================================================
  /tenants:
    get:
      tags: [Tenants]
      summary: List tenants
      description: |
        Lists tenants as a paginated envelope. Supply `parentTenantId` to list the
        children of a parent; omit it to list root tenants. Sort by `createdAt` or
        `slug`.
      operationId: listTenants
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
        - name: parentTenantId
          in: query
          required: false
          description: Parent tenant id. Omit to list root tenants.
          schema:
            type: string
          example: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        - $ref: './common-components.yml#/components/parameters/Limit'
        - $ref: './common-components.yml#/components/parameters/Offset'
        - $ref: './common-components.yml#/components/parameters/Page'
        - $ref: './common-components.yml#/components/parameters/Size'
        - name: sort
          in: query
          required: false
          description: Field to sort by.
          schema:
            type: string
            enum: [createdAt, slug]
            default: createdAt
        - $ref: './common-components.yml#/components/parameters/SortDirection'
      responses:
        '200':
          description: Paginated tenant list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantPage'
              example:
                data:
                  - id: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                    tenantType: organization
                    name: Acme Corporation
                    description: Acme issuing and verification tenant
                    slug: acme
                    parentTenantId: null
                    status: ACTIVE
                    system: false
                    ownerPartyId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
                    createdAt: '2026-06-08T09:00:00Z'
                    createdById: null
                    updatedAt: '2026-06-08T09:00:00Z'
                    updatedById: null
                    deletedAt: null
                    deletedById: null
                pagination:
                  limit: 20
                  offset: 0
                  page: 0
                  size: 20
                  total: 1
                  totalPages: 1
                  hasMore: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [Tenants]
      summary: Register a tenant
      description: |
        Registers a tenant with a default authorization server and an owner
        bootstrap. The owner is supplied as local contact details; choose how the
        owner invitation is delivered with `ownerDelivery.mode`.
      operationId: registerTenant
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterTenantRequest'
            example:
              tenantType: organization
              name: Acme Corporation
              description: Acme issuing and verification tenant
              slug: acme
              parentTenantId: null
              initialPlatformSubdomain: true
              owner:
                type: local
                email: admin@acme.example
                displayName: Acme Administrator
              ownerDelivery:
                mode: email
      responses:
        '201':
          description: Tenant registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterTenantResponse'
              example:
                tenant:
                  id: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                  tenantType: organization
                  name: Acme Corporation
                  description: Acme issuing and verification tenant
                  slug: acme
                  parentTenantId: null
                  status: PENDING_VERIFICATION
                  system: false
                  ownerPartyId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
                  createdAt: '2026-06-08T09:00:00Z'
                  createdById: null
                  updatedAt: '2026-06-08T09:00:00Z'
                  updatedById: null
                  deletedAt: null
                  deletedById: null
                primaryDomainUrl: https://acme.wallet.platform.example
                issuerUrl: https://acme.wallet.platform.example/acme/oid4vci
                ownerUserId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
                correlationId: reg-acme-7f12a7c4
                ownerDelivery:
                  mode: email
                  status: SENT
                  deliveryId: del-7f12a7c4
                  providerMessageId: msg-001
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tenants/{tenantId}:
    get:
      tags: [Tenants]
      summary: Get tenant
      description: Returns a single tenant by id.
      operationId: getTenant
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags: [Tenants]
      summary: Delete tenant
      description: Soft-deletes the tenant routing row.
      operationId: deleteTenant
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Tenant deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
              example:
                deleted: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenantId}/lifecycle/status:
    patch:
      tags: [Tenants]
      summary: Update tenant status
      description: Updates a tenant's lifecycle status and returns the updated tenant.
      operationId: updateTenantStatus
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTenantStatusRequest'
            example:
              status: SUSPENDED
      responses:
        '200':
          description: Updated tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenantId}/domains:
    get:
      tags: [Tenants]
      summary: List tenant domains
      description: Lists the domains attached to a tenant.
      operationId: listTenantDomains
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Tenant domains.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDomainList'
              example:
                data:
                  - id: dom-acme-platform
                    tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                    domain: acme.wallet.platform.example
                    kind: PLATFORM_SUBDOMAIN
                    isPrimary: true
                    verifiedAt: '2026-06-08T09:00:00Z'
                    createdAt: '2026-06-08T09:00:00Z'
                    updatedAt: '2026-06-08T09:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [Tenants]
      summary: Add tenant domain
      description: Attaches a domain (platform subdomain or custom) to a tenant.
      operationId: addTenantDomain
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddTenantDomainRequest'
            example:
              domain: wallet.acme.example
              kind: CUSTOM_DOMAIN
              isPrimary: false
      responses:
        '201':
          description: Domain added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDomain'
              example:
                id: dom-acme-custom
                tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                domain: wallet.acme.example
                kind: CUSTOM_DOMAIN
                isPrimary: false
                verifiedAt: null
                createdAt: '2026-06-08T09:25:00Z'
                updatedAt: '2026-06-08T09:25:00Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tenants/{tenantId}/domains/{domain}:
    delete:
      tags: [Tenants]
      summary: Remove tenant domain
      description: Detaches a domain from a tenant.
      operationId: removeTenantDomain
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
        - $ref: './platform-admin-components.yml#/components/parameters/Domain'
      responses:
        '200':
          description: Domain removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
              example:
                deleted: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenantId}/domains/{domain}/verify:
    post:
      tags: [Tenants]
      summary: Verify tenant custom domain
      description: |
        Submits a DNS challenge proof to verify a custom domain and returns the
        updated domain. The verification proof is write-only.
      operationId: markTenantDomainVerified
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
        - $ref: './platform-admin-components.yml#/components/parameters/Domain'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyTenantDomainRequest'
            example:
              verificationProof: dns-challenge-0a1b2c3d4e5f
      responses:
        '200':
          description: Domain verified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantDomain'
              example:
                id: dom-acme-custom
                tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                domain: wallet.acme.example
                kind: CUSTOM_DOMAIN
                isPrimary: false
                verifiedAt: '2026-06-08T09:30:00Z'
                createdAt: '2026-06-08T09:25:00Z'
                updatedAt: '2026-06-08T09:30:00Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/{tenantId}/children:
    get:
      tags: [Tenants]
      summary: List immediate child tenants
      description: Lists the immediate children of a parent tenant as a paginated envelope. Sort by `createdAt` or `slug`.
      operationId: listSubtenants
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/Limit'
        - $ref: './common-components.yml#/components/parameters/Offset'
        - $ref: './common-components.yml#/components/parameters/Page'
        - $ref: './common-components.yml#/components/parameters/Size'
        - name: sort
          in: query
          required: false
          description: Field to sort by.
          schema:
            type: string
            enum: [createdAt, slug]
            default: createdAt
        - $ref: './common-components.yml#/components/parameters/SortDirection'
      responses:
        '200':
          description: Paginated child tenant list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantPage'
              example:
                data:
                  - id: 9d4e1a2b-3c5f-4e80-a1b2-c3d4e5f60718
                    tenantType: organization
                    name: Acme EU
                    description: Acme European subtenant
                    slug: acme-eu
                    parentTenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                    status: ACTIVE
                    system: false
                    ownerPartyId: null
                    createdAt: '2026-06-08T10:00:00Z'
                    createdById: null
                    updatedAt: '2026-06-08T10:00:00Z'
                    updatedById: null
                    deletedAt: null
                    deletedById: null
                pagination:
                  limit: 20
                  offset: 0
                  page: 0
                  size: 20
                  total: 1
                  totalPages: 1
                  hasMore: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tenants/{tenantId}/public-endpoints:
    get:
      tags: [Tenants]
      summary: List tenant public endpoint bindings
      description: Lists the public endpoint bindings for a tenant.
      operationId: listTenantPublicEndpoints
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Public endpoint bindings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantPublicEndpointList'
              example:
                data:
                  - id: pep-acme-issuer
                    tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                    serviceType: OID4VCI_ISSUER
                    instanceId: null
                    host: acme.wallet.platform.example
                    pathPrefix: /acme/oid4vci
                    wellKnownPath: /.well-known/openid-credential-issuer/acme
                    enabled: true
                    primaryEndpoint: true
                    createdAt: '2026-06-08T09:00:00Z'
                    updatedAt: '2026-06-08T09:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tenants/{tenantId}/public-endpoints/{serviceType}:
    put:
      tags: [Tenants]
      summary: Create or update tenant public endpoint binding
      description: Creates or updates the public endpoint binding for a tenant and service type.
      operationId: upsertTenantPublicEndpoint
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
        - $ref: './platform-admin-components.yml#/components/parameters/PublicEndpointServiceType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertTenantPublicEndpointRequest'
            example:
              host: acme.wallet.platform.example
              pathPrefix: /acme/oid4vci
              wellKnownPath: /.well-known/openid-credential-issuer/acme
              enabled: true
              primaryEndpoint: true
      responses:
        '200':
          description: Public endpoint binding.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantPublicEndpoint'
              example:
                id: pep-acme-issuer
                tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                serviceType: OID4VCI_ISSUER
                instanceId: null
                host: acme.wallet.platform.example
                pathPrefix: /acme/oid4vci
                wellKnownPath: /.well-known/openid-credential-issuer/acme
                enabled: true
                primaryEndpoint: true
                createdAt: '2026-06-08T09:00:00Z'
                updatedAt: '2026-06-08T09:35:00Z'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      tags: [Tenants]
      summary: Delete tenant public endpoint binding
      description: Deletes the public endpoint binding for a tenant and service type.
      operationId: deleteTenantPublicEndpoint
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/TenantId'
        - $ref: './platform-admin-components.yml#/components/parameters/PublicEndpointServiceType'
      responses:
        '200':
          description: Public endpoint binding deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
              example:
                deleted: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenant-onboarding/{correlationId}:
    get:
      tags: [Tenants]
      summary: Get tenant onboarding status
      description: |
        Returns the public-safe lifecycle status of a tenant registration attempt,
        including the per-step timeline, keyed by the `correlationId` returned at
        registration.
      operationId: getTenantOnboardingStatus
      parameters:
        - name: correlationId
          in: path
          required: true
          description: Durable registration-log identifier returned at registration.
          schema:
            type: string
          example: reg-acme-7f12a7c4
      responses:
        '200':
          description: Onboarding status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantOnboardingStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # =====================================================================
  # TenantSignup
  # =====================================================================
  /tenants/signup/request:
    post:
      tags: [TenantSignup]
      summary: Request tenant signup email verification
      description: |
        Public entry point. Starts a self-service signup and sends an email
        verification to the supplied address. Returns the signup request id, its
        expiry, whether operator approval is required, and the email delivery
        result.
      operationId: requestTenantSignup
      x-license-protection:
        entitlementKey: vdx.tenant.signup.request
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestTenantSignupRequest'
            example:
              email: admin@acme.example
              slug: acme
              parentTenantId: null
              displayName: Acme Corporation
      responses:
        '202':
          description: Signup request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSignupRequestAccepted'
              example:
                signupRequestId: signup-9f12a7c4
                expiresAt: '2026-06-09T09:00:00Z'
                requiresApproval: true
                emailDelivery:
                  status: SENT
                  deliveryId: del-9f12a7c4
                  providerMessageId: msg-101
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /tenants/signup/{signupRequestId}/resend:
    post:
      tags: [TenantSignup]
      summary: Resend tenant signup email verification
      description: Public entry point. Re-mints and resends the verification email for a pending signup request.
      operationId: resendTenantSignupVerification
      x-license-protection:
        entitlementKey: vdx.tenant.signup.resend-verification
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      security: []
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/SignupRequestId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResendTenantSignupVerificationRequest'
            example:
              sourceIpHash: 8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4
      responses:
        '202':
          description: Verification resend accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSignupRequestAccepted'
              example:
                signupRequestId: signup-9f12a7c4
                expiresAt: '2026-06-09T10:00:00Z'
                requiresApproval: true
                emailDelivery:
                  status: SENT
                  deliveryId: del-9f12a7c5
                  providerMessageId: msg-102
        '400':
          $ref: '#/components/responses/ValidationError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /tenants/signup/confirm:
    post:
      tags: [TenantSignup]
      summary: Confirm tenant signup email token
      description: |
        Public entry point. Confirms a signup using the plaintext verification
        token from the email. When approval is not required the response carries
        the resulting registration. The verification token is write-only.
      operationId: confirmTenantSignup
      x-license-protection:
        entitlementKey: vdx.tenant.signup.confirm
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
        quotaKeys: [tenants.total.max]
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfirmTenantSignupRequest'
            example:
              plainVerificationToken: vt-2f9a4c7e1b6d8038
      responses:
        '200':
          description: Signup confirmation handled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmTenantSignupResponse'
              example:
                signupRequestId: signup-9f12a7c4
                status: PENDING_APPROVAL
        '400':
          $ref: '#/components/responses/ValidationError'
  /tenants/signup/pending:
    get:
      tags: [TenantSignup]
      summary: List pending tenant signups
      description: |
        Lists pending signup requests as a paginated envelope. Supply
        `parentTenantId` to scope to a parent; omit it to list root signups. Sort
        by `createdAt` or `email`.
      operationId: listPendingTenantSignups
      x-license-protection:
        entitlementKey: vdx.tenant.signup.list-pending
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      parameters:
        - $ref: './common-components.yml#/components/parameters/TenantId'
        - $ref: './common-components.yml#/components/parameters/UserId'
        - name: parentTenantId
          in: query
          required: false
          description: Parent tenant id. Omit to list root signups.
          schema:
            type: string
          example: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        - $ref: './common-components.yml#/components/parameters/Limit'
        - $ref: './common-components.yml#/components/parameters/Offset'
        - $ref: './common-components.yml#/components/parameters/Page'
        - $ref: './common-components.yml#/components/parameters/Size'
        - name: sort
          in: query
          required: false
          description: Field to sort by.
          schema:
            type: string
            enum: [createdAt, email]
            default: createdAt
        - $ref: './common-components.yml#/components/parameters/SortDirection'
      responses:
        '200':
          description: Paginated pending signup requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSignupRequestViewPage'
              example:
                data:
                  - id: signup-9f12a7c4
                    email: admin@acme.example
                    slug: acme
                    parentTenantId: null
                    displayName: Acme Corporation
                    expiresAt: '2026-06-09T09:00:00Z'
                    status: PENDING_APPROVAL
                    createdAt: '2026-06-08T09:00:00Z'
                    emailVerifiedAt: '2026-06-08T09:05:00Z'
                    approvedAt: null
                    approvedById: null
                    confirmedAt: null
                    rejectedAt: null
                    rejectedReason: null
                    registeredTenantId: null
                    registeredAt: null
                    failureReason: null
                    lastResendAt: null
                    resendCount: 0
                pagination:
                  limit: 20
                  offset: 0
                  page: 0
                  size: 20
                  total: 1
                  totalPages: 1
                  hasMore: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /tenants/signup/{signupRequestId}/approve:
    post:
      tags: [TenantSignup]
      summary: Approve pending tenant signup
      description: |
        Approves an email-verified signup request and drives it to registration.
        When registration completes the response carries the resulting
        registration.
      operationId: approveTenantSignup
      x-license-protection:
        entitlementKey: vdx.tenant.signup.approve
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
        quotaKeys: [tenants.total.max]
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/SignupRequestId'
      responses:
        '200':
          description: Signup approval handled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApproveTenantSignupResponse'
              example:
                signupRequestId: signup-9f12a7c4
                status: REGISTERED
                registration:
                  tenant:
                    id: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
                    tenantType: organization
                    name: Acme Corporation
                    description: null
                    slug: acme
                    parentTenantId: null
                    status: PENDING_VERIFICATION
                    system: false
                    ownerPartyId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
                    createdAt: '2026-06-08T09:40:00Z'
                    createdById: null
                    updatedAt: '2026-06-08T09:40:00Z'
                    updatedById: null
                    deletedAt: null
                    deletedById: null
                  primaryDomainUrl: https://acme.wallet.platform.example
                  issuerUrl: https://acme.wallet.platform.example/acme/oid4vci
                  ownerUserId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
                  correlationId: reg-acme-7f12a7c4
                  ownerDelivery:
                    mode: none
                    status: NOT_REQUESTED
                    deliveryId: null
                    providerMessageId: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/signup/{signupRequestId}/reject:
    post:
      tags: [TenantSignup]
      summary: Reject pending tenant signup
      description: Rejects a pending signup request with an optional reason.
      operationId: rejectTenantSignup
      x-license-protection:
        entitlementKey: vdx.tenant.signup.reject
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/SignupRequestId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectTenantSignupRequest'
            example:
              reason: Domain ownership could not be confirmed.
      responses:
        '200':
          description: Signup rejected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RejectResult'
              example:
                rejected: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /tenants/signup/reconcile/expired:
    post:
      tags: [TenantSignup]
      summary: Mark expired pending tenant signups
      description: Marks pending signup requests whose expiry has passed as expired, relative to the supplied `now`.
      operationId: reconcileExpiredTenantSignups
      x-license-protection:
        entitlementKey: vdx.tenant.signup.reconcile-expired
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReconcileExpiredTenantSignupsRequest'
            example:
              now: '2026-06-09T09:00:00Z'
      responses:
        '200':
          description: Expired signup reconciliation completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconcileExpiredTenantSignupsResponse'
              example:
                expiredCount: 3
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  # =====================================================================
  # TenantFederation
  # =====================================================================
  /federation/idps:
    get:
      tags: [TenantFederation]
      summary: List tenant identity providers
      description: Lists the calling tenant's external identity providers.
      operationId: listTenantIdps
      x-license-protection:
        entitlementKey: vdx.tenant.federation.list-idps
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      responses:
        '200':
          description: Tenant identity providers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdpList'
              example:
                data:
                  - idpId: idp-acme-corp
                    displayName: Acme Corporate IdP
                    issuer: https://idp.acme.example
                    clientId: acme-client
                    clientSecretRef: secret://tenant-acme/idp/acme-client-secret
                    scopes: [openid, profile, email]
                    claimsMapping:
                      subject: sub
                      email: email
                      displayName: name
                    enabled: true
                    createdAt: '2026-06-08T09:10:00Z'
                    updatedAt: '2026-06-08T09:10:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags: [TenantFederation]
      summary: Create a tenant identity provider
      description: |
        Creates an external identity provider for the calling tenant. Supply
        `clientSecret` as plaintext exactly once; it is stored through the secret
        backend and returned only as `clientSecretRef`.
      operationId: createTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.create-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantIdpWrite'
            example:
              displayName: Acme Corporate IdP
              issuer: https://idp.acme.example
              clientId: acme-client
              clientSecret: s3cr3t-acme-client-value
              scopes: [openid, profile, email]
              claimsMapping:
                subject: sub
                email: email
                displayName: name
              enabled: false
      responses:
        '201':
          description: Created tenant identity provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdp'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
  /federation/idps/{idpId}:
    parameters:
      - $ref: './platform-admin-components.yml#/components/parameters/IdpId'
    get:
      tags: [TenantFederation]
      summary: Get a tenant identity provider
      description: Returns a single tenant identity provider by id.
      operationId: getTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.get-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      responses:
        '200':
          description: Tenant identity provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdp'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags: [TenantFederation]
      summary: Replace a tenant identity provider
      description: |
        Replaces a tenant identity provider. Supply `clientSecret` as plaintext to
        rotate it; supply `clientSecretRef` to preserve the existing reference;
        omit both to clear it. The plaintext secret is never echoed.
      operationId: putTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.put-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantIdpWrite'
            example:
              displayName: Acme Corporate IdP
              issuer: https://idp.acme.example
              clientId: acme-client
              clientSecretRef: secret://tenant-acme/idp/acme-client-secret
              scopes: [openid, profile, email]
              claimsMapping:
                subject: sub
                email: email
                displayName: name
              enabled: true
      responses:
        '200':
          description: Updated tenant identity provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdp'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      tags: [TenantFederation]
      summary: Delete a tenant identity provider
      description: Deletes a tenant identity provider by id.
      operationId: deleteTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.delete-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      responses:
        '200':
          description: Delete result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
              example:
                deleted: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /federation/idps/{idpId}/test:
    post:
      tags: [TenantFederation]
      summary: Test identity provider connectivity and metadata
      description: Probes an identity provider's issuer reachability and metadata validity.
      operationId: testTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.test-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/IdpId'
      responses:
        '200':
          description: Test result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdpTestResult'
              example:
                success: true
                issuerReachable: true
                metadataValid: true
                error: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /federation/idps/{idpId}/enable:
    post:
      tags: [TenantFederation]
      summary: Enable an identity provider
      description: Enables a tenant identity provider for sign-in and returns it.
      operationId: enableTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.enable-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/IdpId'
      responses:
        '200':
          description: Enabled identity provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdp'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /federation/idps/{idpId}/disable:
    post:
      tags: [TenantFederation]
      summary: Disable an identity provider
      description: Disables a tenant identity provider and returns it.
      operationId: disableTenantIdp
      x-license-protection:
        entitlementKey: vdx.tenant.federation.disable-idp
        deploymentShapePredicates: [packaging=container, environment=production]
        protectionMode: licensed
      parameters:
        - $ref: './platform-admin-components.yml#/components/parameters/IdpId'
      responses:
        '200':
          description: Disabled identity provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantIdp'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  # =====================================================================
  # OwnerBootstrap
  # =====================================================================
  /owner/redeem:
    post:
      tags: [OwnerBootstrap]
      summary: Redeem owner invitation
      description: |
        Public entry point. Redeems a one-time owner invitation token, sets the
        owner's credential, and activates the owner account. Both the token and
        the credential are write-only.
      operationId: redeemOwnerInvitation
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemOwnerInvitationRequest'
            example:
              token: inv-7f12a7c4-2f9a4c7e1b6d8038
              credential: new-owner-passphrase
      responses:
        '200':
          description: Owner invitation redeemed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemOwnerInvitationResponse'
              example:
                ownerUserId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
                tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    bearer:
      $ref: './common-components.yml#/components/securitySchemes/bearer'
  responses:
    # Error responses use the {error} envelope (ErrorResponse) that the runtime emits.
    ValidationError:
      description: The request failed validation. Body is the `{error}` envelope.
      content:
        application/json:
          schema:
            $ref: './common-components.yml#/components/schemas/ErrorResponse'
          example:
            error:
              code: VALIDATION_ERROR
              message: slug must match ^[a-z][a-z0-9-]{0,62}$
              correlationId: 7f12a7c4-1b6d-4038-9a4c-2f9a4c7e1b6d
    Unauthorized:
      description: Authentication is missing or invalid. Body is the `{error}` envelope.
      content:
        application/json:
          schema:
            $ref: './common-components.yml#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required
              correlationId: 7f12a7c4-1b6d-4038-9a4c-2f9a4c7e1b6d
    Forbidden:
      description: The caller is not authorised for this operation. Body is the `{error}` envelope.
      content:
        application/json:
          schema:
            $ref: './common-components.yml#/components/schemas/ErrorResponse'
          example:
            error:
              code: FORBIDDEN
              message: Insufficient permissions
              correlationId: 7f12a7c4-1b6d-4038-9a4c-2f9a4c7e1b6d
    NotFound:
      description: The requested entity was not found. Body is the `{error}` envelope.
      content:
        application/json:
          schema:
            $ref: './common-components.yml#/components/schemas/ErrorResponse'
          example:
            error:
              code: NOT_FOUND
              message: 'tenant not found: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01'
              correlationId: 7f12a7c4-1b6d-4038-9a4c-2f9a4c7e1b6d
    Conflict:
      description: The resource conflicts with existing configuration. Body is the `{error}` envelope.
      content:
        application/json:
          schema:
            $ref: './common-components.yml#/components/schemas/ErrorResponse'
          example:
            error:
              code: CONFLICT
              message: An identity provider with this issuer already exists.
              correlationId: 7f12a7c4-1b6d-4038-9a4c-2f9a4c7e1b6d
    RateLimited:
      description: The rate limit was exceeded. Body is the `{error}` envelope.
      content:
        application/json:
          schema:
            $ref: './common-components.yml#/components/schemas/ErrorResponse'
          example:
            error:
              code: RATE_LIMITED
              message: Too many signup attempts. Try again later.
              correlationId: 7f12a7c4-1b6d-4038-9a4c-2f9a4c7e1b6d
  schemas:
    # ---- PlatformAdmin entity schemas (externalized) ----
    ApplicationTenantStatus:
      $ref: './platform-admin-components.yml#/components/schemas/ApplicationTenantStatus'
    LicenseStatusProjection:
      $ref: './platform-admin-components.yml#/components/schemas/LicenseStatusProjection'
    ProductLicenseSummary:
      $ref: './platform-admin-components.yml#/components/schemas/ProductLicenseSummary'
    LicenseVerificationProjection:
      $ref: './platform-admin-components.yml#/components/schemas/LicenseVerificationProjection'
    SecretBackendStatus:
      $ref: './platform-admin-components.yml#/components/schemas/SecretBackendStatus'
    SecretBackendType:
      $ref: './platform-admin-components.yml#/components/schemas/SecretBackendType'
    OnboardingPolicy:
      $ref: './platform-admin-components.yml#/components/schemas/OnboardingPolicy'
    OnboardingAvailability:
      $ref: './platform-admin-components.yml#/components/schemas/OnboardingAvailability'

    # ---- PlatformAdmin request bodies (inline) ----
    ApplicationTenantBootstrapRequest:
      type: object
      description: Optional operator contact details seeded into the bootstrapped application tenant.
      properties:
        operatorEmail:
          type: string
          format: email
          nullable: true
          description: Initial operator email address.
        operatorDisplayName:
          type: string
          nullable: true
          description: Initial operator display name.
      example:
        operatorEmail: admin@acme.example
        operatorDisplayName: Acme Administrator
    LicenseActivationRequest:
      type: object
      description: License token to install or verify.
      required: [licenseToken]
      properties:
        licenseToken:
          type: string
          writeOnly: true
          description: Signed license token. Write-only; never echoed.
      example:
        licenseToken: eyJhbGciOiJFZERTQSJ9.eyJ0aWVyIjoicHJvIn0.signature
    SecretBackendWrite:
      type: object
      description: Secret backend selection.
      required: [backend]
      properties:
        backend:
          $ref: '#/components/schemas/SecretBackendType'
        configRef:
          type: string
          nullable: true
          description: Opaque reference to the resolved backend instance.
      example:
        backend: hashicorp-vault
        configRef: secret://platform/kv/tenant-secrets
    OnboardingPolicyWrite:
      type: object
      description: >
        Onboarding policy update. Every field is optional; a field left unset
        leaves that toggle unchanged.
      properties:
        rootTenantCreationEnabled:
          type: boolean
          nullable: true
          description: When set, enables or disables operator root-tenant creation.
        adminInviteEnabled:
          type: boolean
          nullable: true
          description: When set, enables or disables operator-driven tenant invitations.
        selfSignupEnabled:
          type: boolean
          nullable: true
          description: When set, enables or disables public self-service signup.
        subtenantSignupEnabled:
          type: boolean
          nullable: true
          description: When set, enables or disables self-service signup under a parent tenant.
        requireApprovalForSelfSignup:
          type: boolean
          nullable: true
          description: When set, toggles whether operator approval is required after email verification.
      example:
        selfSignupEnabled: true
        requireApprovalForSelfSignup: true

    # ---- Tenants entity schemas (externalized) ----
    Tenant:
      $ref: './platform-admin-components.yml#/components/schemas/Tenant'
    TenantStatus:
      $ref: './platform-admin-components.yml#/components/schemas/TenantStatus'
    TenantDomain:
      $ref: './platform-admin-components.yml#/components/schemas/TenantDomain'
    TenantDomainKind:
      $ref: './platform-admin-components.yml#/components/schemas/TenantDomainKind'
    TenantPublicEndpoint:
      $ref: './platform-admin-components.yml#/components/schemas/TenantPublicEndpoint'
    TenantPublicEndpointServiceType:
      $ref: './platform-admin-components.yml#/components/schemas/TenantPublicEndpointServiceType'
    TenantOnboardingStatus:
      $ref: './platform-admin-components.yml#/components/schemas/TenantOnboardingStatus'
    OwnerDeliveryMode:
      $ref: './platform-admin-components.yml#/components/schemas/OwnerDeliveryMode'
    OwnerDeliveryStatus:
      $ref: './platform-admin-components.yml#/components/schemas/OwnerDeliveryStatus'
    SignupEmailDeliveryStatus:
      $ref: './platform-admin-components.yml#/components/schemas/SignupEmailDeliveryStatus'
    TenantSignupStatus:
      $ref: './platform-admin-components.yml#/components/schemas/TenantSignupStatus'
    TenantSignupRequestView:
      $ref: './platform-admin-components.yml#/components/schemas/TenantSignupRequestView'
    LocalOwnerInput:
      $ref: './platform-admin-components.yml#/components/schemas/LocalOwnerInput'

    # ---- Shared result envelopes ----
    DeleteResult:
      $ref: './platform-admin-components.yml#/components/schemas/DeleteResult'
    RejectResult:
      $ref: './platform-admin-components.yml#/components/schemas/RejectResult'

    # ---- Tenants list envelopes ----
    TenantPage:
      type: object
      description: Paginated tenant list.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tenant'
        pagination:
          $ref: './common-components.yml#/components/schemas/PageMeta'
    TenantDomainList:
      type: object
      description: Non-paginated tenant domain list.
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TenantDomain'
    TenantPublicEndpointList:
      type: object
      description: Non-paginated tenant public endpoint list.
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TenantPublicEndpoint'

    # ---- Tenants request/response bodies (inline) ----
    RegisterTenantRequest:
      type: object
      description: Tenant registration request. The owner is supplied as local contact details.
      required: [tenantType, name, slug, owner]
      properties:
        tenantType:
          type: string
          description: Open tenant type label.
        name:
          type: string
          description: Human-readable tenant name.
        description:
          type: string
          nullable: true
          description: Optional tenant description.
        slug:
          type: string
          pattern: '^[a-z][a-z0-9-]{0,62}$'
          description: Globally unique URL-safe slug.
        parentTenantId:
          type: string
          nullable: true
          description: Parent tenant id for a subtenant, or null for a root tenant.
        ownerPartyId:
          type: string
          format: uuid
          nullable: true
          description: Existing party id to use as the owner, when provided.
        initialPlatformSubdomain:
          type: boolean
          default: true
          description: Whether to auto-create the platform subdomain at registration.
        owner:
          $ref: '#/components/schemas/LocalOwnerInput'
        ownerDelivery:
          $ref: '#/components/schemas/OwnerDeliveryRequest'
      example:
        tenantType: organization
        name: Acme Corporation
        description: Acme issuing and verification tenant
        slug: acme
        parentTenantId: null
        initialPlatformSubdomain: true
        owner:
          type: local
          email: admin@acme.example
          displayName: Acme Administrator
        ownerDelivery:
          mode: email
    OwnerDeliveryRequest:
      type: object
      description: How to deliver the owner invitation.
      properties:
        mode:
          allOf:
            - $ref: '#/components/schemas/OwnerDeliveryMode'
          default: none
          description: >
            Delivery mode. `none` mints the invitation without sending it; `email`
            sends it through the configured email transport. `manual` is not
            accepted and is rejected with a `403`.
      example:
        mode: email
    RegisterTenantResponse:
      type: object
      description: Result of registering a tenant, including the owner-delivery outcome.
      required: [tenant, primaryDomainUrl, ownerUserId, correlationId, ownerDelivery]
      properties:
        tenant:
          $ref: '#/components/schemas/Tenant'
        primaryDomainUrl:
          type: string
          format: uri
          description: Primary reachable URL for the tenant.
        issuerUrl:
          type: string
          format: uri
          nullable: true
          description: Issuer URL of the default authorization server, when provisioned.
        ownerUserId:
          type: string
          description: Identifier of the created owner user.
        correlationId:
          type: string
          description: Durable registration-log id for polling onboarding status.
        ownerDelivery:
          $ref: '#/components/schemas/OwnerDeliveryResponse'
      example:
        tenant:
          id: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
          tenantType: organization
          name: Acme Corporation
          description: Acme issuing and verification tenant
          slug: acme
          parentTenantId: null
          status: PENDING_VERIFICATION
          system: false
          ownerPartyId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
          createdAt: '2026-06-08T09:00:00Z'
          createdById: null
          updatedAt: '2026-06-08T09:00:00Z'
          updatedById: null
          deletedAt: null
          deletedById: null
        primaryDomainUrl: https://acme.wallet.platform.example
        issuerUrl: https://acme.wallet.platform.example/acme/oid4vci
        ownerUserId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
        correlationId: reg-acme-7f12a7c4
        ownerDelivery:
          mode: email
          status: SENT
          deliveryId: del-7f12a7c4
          providerMessageId: msg-001
    OwnerDeliveryResponse:
      type: object
      description: Outcome of the owner invitation delivery.
      required: [mode, status]
      properties:
        mode:
          $ref: '#/components/schemas/OwnerDeliveryMode'
        status:
          $ref: '#/components/schemas/OwnerDeliveryStatus'
        deliveryId:
          type: string
          nullable: true
          description: Delivery correlation id, when available.
        providerMessageId:
          type: string
          nullable: true
          description: Email provider message id, when available.
      example:
        mode: email
        status: SENT
        deliveryId: del-7f12a7c4
        providerMessageId: msg-001
    UpdateTenantStatusRequest:
      type: object
      description: Tenant status update.
      required: [status]
      properties:
        status:
          $ref: '#/components/schemas/TenantStatus'
      example:
        status: SUSPENDED
    AddTenantDomainRequest:
      type: object
      description: Domain to attach to a tenant.
      required: [domain, kind]
      properties:
        domain:
          type: string
          description: Lowercased host without scheme or port.
        kind:
          $ref: '#/components/schemas/TenantDomainKind'
        isPrimary:
          type: boolean
          default: false
          description: Whether this domain becomes the canonical issuer host.
      example:
        domain: wallet.acme.example
        kind: CUSTOM_DOMAIN
        isPrimary: false
    VerifyTenantDomainRequest:
      type: object
      description: DNS challenge proof for a custom domain.
      required: [verificationProof]
      properties:
        verificationProof:
          type: string
          writeOnly: true
          description: Proof value matching the domain's stored verification token. Write-only.
      example:
        verificationProof: dns-challenge-0a1b2c3d4e5f
    UpsertTenantPublicEndpointRequest:
      type: object
      description: Public endpoint binding to create or update for a tenant and service type.
      properties:
        host:
          type: string
          nullable: true
          description: Lowercased host without scheme or port. Null uses the runtime host or default base.
        pathPrefix:
          type: string
          nullable: true
          description: Protocol route prefix, for example `/acme/oid4vci`.
        wellKnownPath:
          type: string
          nullable: true
          description: Well-known route, for example `/.well-known/openid-credential-issuer/acme`.
        enabled:
          type: boolean
          default: true
          description: Whether the binding is active.
        primaryEndpoint:
          type: boolean
          default: false
          description: Whether this is the primary binding for the tenant and service type.
      example:
        host: acme.wallet.platform.example
        pathPrefix: /acme/oid4vci
        wellKnownPath: /.well-known/openid-credential-issuer/acme
        enabled: true
        primaryEndpoint: true

    # ---- TenantSignup request/response bodies (inline) ----
    RequestTenantSignupRequest:
      type: object
      description: Self-service signup request.
      required: [email, slug, displayName]
      properties:
        email:
          type: string
          format: email
          description: Requester email address. The verification email is sent here.
        slug:
          type: string
          pattern: '^[a-z][a-z0-9-]{0,62}$'
          description: Requested tenant slug.
        parentTenantId:
          type: string
          nullable: true
          description: Parent tenant for a subtenant signup, or null for a root signup.
        displayName:
          type: string
          description: Requested tenant display name.
        challengeProof:
          type: string
          nullable: true
          description: Bot-defence challenge proof, when the deployment requires one.
      example:
        email: admin@acme.example
        slug: acme
        parentTenantId: null
        displayName: Acme Corporation
    TenantSignupRequestAccepted:
      type: object
      description: Acknowledgement of an accepted signup request or resend.
      required: [signupRequestId, expiresAt, requiresApproval, emailDelivery]
      properties:
        signupRequestId:
          type: string
          description: Identifier of the signup request.
        expiresAt:
          type: string
          format: date-time
          description: Expiry of the signup request.
        requiresApproval:
          type: boolean
          description: Whether operator approval is required after email verification.
        emailDelivery:
          $ref: '#/components/schemas/SignupEmailDeliveryResponse'
      example:
        signupRequestId: signup-9f12a7c4
        expiresAt: '2026-06-09T09:00:00Z'
        requiresApproval: true
        emailDelivery:
          status: SENT
          deliveryId: del-9f12a7c4
          providerMessageId: msg-101
    SignupEmailDeliveryResponse:
      type: object
      description: Outcome of the signup verification email delivery.
      required: [status]
      properties:
        status:
          $ref: '#/components/schemas/SignupEmailDeliveryStatus'
        deliveryId:
          type: string
          nullable: true
          description: Delivery correlation id, when available.
        providerMessageId:
          type: string
          nullable: true
          description: Email provider message id, when available.
      example:
        status: SENT
        deliveryId: del-9f12a7c4
        providerMessageId: msg-101
    ResendTenantSignupVerificationRequest:
      type: object
      description: Optional body for a verification resend.
      properties:
        sourceIpHash:
          type: string
          nullable: true
          description: Hashed source IP for rate limiting and audit.
      example:
        sourceIpHash: 8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4
    ConfirmTenantSignupRequest:
      type: object
      description: Email confirmation for a signup request.
      required: [plainVerificationToken]
      properties:
        plainVerificationToken:
          type: string
          writeOnly: true
          description: Plaintext verification token from the email. Write-only.
      example:
        plainVerificationToken: vt-2f9a4c7e1b6d8038
    ConfirmTenantSignupResponse:
      type: object
      description: Result of confirming a signup. Registration is present when approval is not required.
      required: [signupRequestId, status]
      properties:
        signupRequestId:
          type: string
          description: Identifier of the signup request.
        status:
          $ref: '#/components/schemas/TenantSignupStatus'
        registration:
          type: object
          allOf:
            - $ref: '#/components/schemas/RegisterTenantResponse'
          nullable: true
          description: Resulting registration when the signup registered.
      example:
        signupRequestId: signup-9f12a7c4
        status: PENDING_APPROVAL
    ApproveTenantSignupResponse:
      type: object
      description: Result of approving a signup. Registration is present when registration completed.
      required: [signupRequestId, status]
      properties:
        signupRequestId:
          type: string
          description: Identifier of the signup request.
        status:
          $ref: '#/components/schemas/TenantSignupStatus'
        registration:
          type: object
          allOf:
            - $ref: '#/components/schemas/RegisterTenantResponse'
          nullable: true
          description: Resulting registration when the signup registered.
      example:
        signupRequestId: signup-9f12a7c4
        status: REGISTERED
        registration:
          tenant:
            id: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
            tenantType: organization
            name: Acme Corporation
            description: null
            slug: acme
            parentTenantId: null
            status: PENDING_VERIFICATION
            system: false
            ownerPartyId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
            createdAt: '2026-06-08T09:40:00Z'
            createdById: null
            updatedAt: '2026-06-08T09:40:00Z'
            updatedById: null
            deletedAt: null
            deletedById: null
          primaryDomainUrl: https://acme.wallet.platform.example
          issuerUrl: https://acme.wallet.platform.example/acme/oid4vci
          ownerUserId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
          correlationId: reg-acme-7f12a7c4
          ownerDelivery:
            mode: none
            status: NOT_REQUESTED
            deliveryId: null
            providerMessageId: null
    TenantSignupRequestViewPage:
      type: object
      description: Paginated pending signup list.
      required: [data, pagination]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TenantSignupRequestView'
        pagination:
          $ref: './common-components.yml#/components/schemas/PageMeta'
    RejectTenantSignupRequest:
      type: object
      description: Optional body for a signup rejection.
      properties:
        reason:
          type: string
          nullable: true
          description: Operator-supplied rejection reason.
      example:
        reason: Domain ownership could not be confirmed.
    ReconcileExpiredTenantSignupsRequest:
      type: object
      description: Reconciliation cutoff.
      required: [now]
      properties:
        now:
          type: string
          format: date-time
          description: Timestamp against which expiry is evaluated.
      example:
        now: '2026-06-09T09:00:00Z'
    ReconcileExpiredTenantSignupsResponse:
      type: object
      description: Number of signup requests marked expired.
      required: [expiredCount]
      properties:
        expiredCount:
          type: integer
          format: int32
          minimum: 0
          description: Count of requests marked expired.
      example:
        expiredCount: 3

    # ---- TenantFederation entity + request schemas ----
    TenantIdp:
      $ref: './platform-admin-components.yml#/components/schemas/TenantIdp'
    ClaimsMapping:
      $ref: './platform-admin-components.yml#/components/schemas/ClaimsMapping'
    TenantIdpTestResult:
      $ref: './platform-admin-components.yml#/components/schemas/TenantIdpTestResult'
    TenantIdpList:
      type: object
      description: Non-paginated tenant identity provider list.
      required: [data]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TenantIdp'
    TenantIdpWrite:
      type: object
      description: >
        Create or replace body for a tenant identity provider. Supply `clientSecret`
        as plaintext exactly once to set or rotate it; it is consumed by the secret
        backend and returned only as `clientSecretRef`.
      required: [displayName, issuer, clientId]
      properties:
        displayName:
          type: string
          description: Human-readable identity provider name.
        issuer:
          type: string
          format: uri
          description: OpenID Connect issuer URL.
        clientId:
          type: string
          description: OAuth2 client identifier registered with the provider.
        clientSecret:
          type: string
          writeOnly: true
          nullable: true
          description: Plaintext client secret. Write-only; stored through the secret backend and never echoed.
        clientSecretRef:
          type: string
          nullable: true
          description: Existing opaque secret reference to preserve when no plaintext secret is supplied.
        scopes:
          type: array
          items:
            type: string
          default: [openid, profile, email]
          description: OAuth2 scopes requested during federation.
        claimsMapping:
          $ref: '#/components/schemas/ClaimsMapping'
        enabled:
          type: boolean
          default: false
          description: Whether the identity provider is enabled on creation.
      example:
        displayName: Acme Corporate IdP
        issuer: https://idp.acme.example
        clientId: acme-client
        clientSecret: s3cr3t-acme-client-value
        scopes: [openid, profile, email]
        claimsMapping:
          subject: sub
          email: email
          displayName: name
        enabled: false

    # ---- OwnerBootstrap request/response bodies (inline) ----
    RedeemOwnerInvitationRequest:
      type: object
      description: Owner invitation redemption.
      required: [token, credential]
      properties:
        token:
          type: string
          writeOnly: true
          description: One-time owner invitation token from the invitation link. Write-only.
        credential:
          type: string
          writeOnly: true
          description: Credential the owner sets on first login. Opaque to this API. Write-only.
      example:
        token: inv-7f12a7c4-2f9a4c7e1b6d8038
        credential: new-owner-passphrase
    RedeemOwnerInvitationResponse:
      type: object
      description: Result of redeeming an owner invitation.
      required: [ownerUserId, tenantId]
      properties:
        ownerUserId:
          type: string
          description: Identifier of the activated owner user.
        tenantId:
          type: string
          description: Identifier of the tenant the owner now administers.
      example:
        ownerUserId: 2c4e6a80-3b5d-4f70-9a12-8c0d1e2f3a4b
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01