platform-config-components.yml

openapi: 3.0.4
info:
  title: Sphereon Platform Config API Components
  version: 0.1.0
  description: >
    Shared schemas for the platform-config API. The API exposes service-instance
    configuration as typed resources and never exposes raw tenant configuration
    rows. Reads return effective values with a per-field source marker so clients
    can see whether a value is tenant-set or inherited from defaults.
paths: {}
components:
  parameters:
    TenantId:
      name: tenantId
      in: path
      required: true
      description: Identifier of the tenant whose service instance is configured.
      schema:
        type: string
      example: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
    AsSlug:
      name: slug
      in: path
      required: true
      description: Authorization-server instance slug. This is the `<slug>` segment in `oauth2.servers.<slug>.*` config keys.
      schema:
        type: string
        pattern: '^[a-z][a-z0-9-]{0,62}$'
      example: default
    KmsProviderId:
      name: providerId
      in: path
      required: true
      description: KMS provider id. This is the `<providerId>` segment in `kms.providers.<providerId>.*` config keys.
      schema:
        type: string
        pattern: '^[a-z0-9][a-z0-9-]*$'
      example: my-hsm
    ClientId:
      name: clientId
      in: path
      required: true
      description: OAuth2 client identifier. URL-encode identifiers that contain reserved path characters.
      schema:
        type: string
      example: wallet-web
    InstanceId:
      name: instanceId
      in: path
      required: true
      description: Service instance id. For VDX-backed OID4VCI/OID4VP instances this is the software party id.
      schema:
        type: string
        format: uuid
      example: 4ca2a7cc-f5ef-4e13-8c0d-6a8bd7f6d211
    IdentityId:
      name: identityId
      in: path
      required: true
      description: Identifier of the authenticating identity registered against the AS.
      schema:
        type: string
        format: uuid
      example: 1d9f5c3a-2b7e-4f81-9c0d-6a8bd7f6d211
    ManagementModeQuery:
      name: managementMode
      in: query
      required: false
      description: Filter instances by who manages the service.
      schema:
        $ref: './software-manager-components.yml#/components/schemas/ManagementMode'
    LifecycleStatusQuery:
      name: lifecycleStatus
      in: query
      required: false
      description: Filter instances by lifecycle status.
      schema:
        $ref: './software-manager-components.yml#/components/schemas/LifecycleStatus'
    PageQuery:
      name: page
      in: query
      required: false
      description: Zero-based result page.
      schema:
        type: integer
        minimum: 0
        default: 0
    SizeQuery:
      name: size
      in: query
      required: false
      description: Number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20

  schemas:
    ValueSource:
      type: string
      description: Origin of an effective configuration value.
      enum: [tenant, default, design]
      example: tenant
    StringConfigField:
      type: object
      required: [value, source]
      properties:
        value:
          type: string
          example: jwt
        source:
          $ref: '#/components/schemas/ValueSource'
    BooleanConfigField:
      type: object
      required: [value, source]
      properties:
        value:
          type: boolean
        source:
          $ref: '#/components/schemas/ValueSource'
    IntegerConfigField:
      type: object
      required: [value, source]
      properties:
        value:
          type: integer
          format: int64
        source:
          $ref: '#/components/schemas/ValueSource'
    StringListConfigField:
      type: object
      required: [value, source]
      properties:
        value:
          type: array
          items:
            type: string
            example: openid
        source:
          $ref: '#/components/schemas/ValueSource'
    FeatureMode:
      type: string
      description: Feature policy value. `required` means clients must use the feature when applicable.
      enum: [disabled, supported, required]
      example: supported
    FeatureConfigField:
      type: object
      required: [value, source]
      properties:
        value:
          $ref: '#/components/schemas/FeatureMode'
        source:
          $ref: '#/components/schemas/ValueSource'
    SecretReference:
      type: object
      description: Reference to secret material resolved by the configuration layer at runtime.
      required: [ref]
      properties:
        ref:
          type: string
          description: Resolvable secret reference (`${secret:<logical-key>[:<key>]}` or `${env:NAME}`). Plaintext secret material is never returned.
          example: ${secret:oauth2/default/internal-clients/admin}
        backendId:
          type: string
          nullable: true
          description: Backend that owns the reference, when known.
          example: tenant-vault
        createdByPlatformConfig:
          type: boolean
          default: false
          description: True when the platform-config API created the reference and may delete it on clear/replace.

    AsInstance:
      type: object
      description: OAuth2/OIDC authorization-server instance backed by `oauth2.servers.<slug>.*` tenant config keys.
      required: [tenantId, slug, issuer, signingAlgorithm, userBacking, scopes, claimMappings]
      properties:
        tenantId:
          type: string
        slug:
          type: string
          pattern: '^[a-z][a-z0-9-]{0,62}$'
        issuer:
          type: string
          format: uri
          description: Issuer URL served by this AS instance.
        signingAlgorithm:
          type: string
          description: Token signing algorithm descriptor stored as `signing-algorithm`.
          example: ES256
        userBacking:
          type: string
          description: User-backing mode for the hosted AS.
          example: local
        scopes:
          type: array
          items:
            type: string
          description: Space-separated in storage as `oauth2.servers.<slug>.scopes`.
        claimMappings:
          type: object
          additionalProperties:
            type: string
          description: Claim mapping rows under `oauth2.servers.<slug>.claim-mappings.*`.
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        slug: default
        issuer: https://auth.acme.example
        signingAlgorithm: ES256
        userBacking: local
        scopes: [openid, profile, email]
        claimMappings:
          email: email
          name: displayName
    CreateAsInstanceRequest:
      allOf:
        - $ref: '#/components/schemas/AsInstance'
      description: Create request for an AS instance. The tenant id in the body must match the path target.
    UpdateAsInstanceRequest:
      type: object
      description: Partial update request for AS instance descriptor fields.
      properties:
        tenantId:
          type: string
        slug:
          type: string
        issuer:
          type: string
          format: uri
        signingAlgorithm:
          type: string
        userBacking:
          type: string
        scopes:
          type: array
          items:
            type: string
        claimMappings:
          type: object
          additionalProperties:
            type: string
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        slug: default
        scopes: [openid, profile, email, address]
    AsInstanceList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AsInstance'
        page:
          $ref: '#/components/schemas/PlatformConfigPageMeta'
    DeleteAsInstanceResult:
      type: object
      required: [deleted]
      properties:
        deleted:
          type: boolean
          description: True when the authorization-server instance existed and was deleted.

    # ---- Email accounts ------------------------------------------------------
    # Email accounts are tenant-owned mail sender configurations. They are represented in the
    # party model as EXTERNAL software entries with an EMAIL_SERVER capability and config rooted at
    # `vdx.service.email.accounts.<accountId>.*`. Accounts created for the platform tenant are the
    # named defaults used by tenant mail delivery unless a tenant defines its own account.

    SmtpAccountConfig:
      type: object
      description: SMTP transport settings for a mail account. Passwords are supplied as secret references only.
      required: [host]
      properties:
        host:
          type: string
          description: SMTP server host name.
          example: smtp.mail.example
        port:
          type: integer
          minimum: 1
          maximum: 65535
          default: 587
          example: 587
        username:
          type: string
          nullable: true
          description: SMTP username when authentication is required.
          example: support@acme.example
        passwordSecretRef:
          type: string
          nullable: true
          writeOnly: true
          description: >
            Resolvable secret reference used for the SMTP password — `${secret:<logical-key>[:<key>]}`
            or `${env:NAME}`. Plaintext passwords are rejected and are never returned.
          example: ${secret:mail/support/password}
        useStarttls:
          type: boolean
          default: true
          description: Use STARTTLS for the SMTP connection.
        useSsl:
          type: boolean
          default: false
          description: Use implicit SSL/TLS for the SMTP connection.
        connectionTimeoutMs:
          type: integer
          format: int64
          minimum: 1
          default: 5000
          description: Connection timeout in milliseconds.
        readTimeoutMs:
          type: integer
          format: int64
          minimum: 1
          default: 10000
          description: Read timeout in milliseconds.

    EmailAccountConfig:
      type: object
      description: Mail sender configuration consumed by the EDK email service.
      required: [fromAddress]
      properties:
        transportId:
          type: string
          default: smtp
          description: Transport implementation id. `smtp` is the currently supported transport.
          example: smtp
        fromAddress:
          type: string
          format: email
          description: Sender email address used by this account.
          example: support@acme.example
        fromName:
          type: string
          nullable: true
          description: Sender display name.
          example: Acme Support
        replyTo:
          type: string
          format: email
          nullable: true
          description: Optional reply-to email address.
          example: helpdesk@acme.example
        smtp:
          $ref: '#/components/schemas/SmtpAccountConfig'

    EmailAccountCreateRequest:
      type: object
      description: >
        Create request for a tenant email account. The account becomes an EXTERNAL / THIRD_PARTY
        EMAIL_SERVER software entry and writes config under `vdx.service.email.accounts.<accountId>.*`.
      required: [displayName, config]
      properties:
        accountId:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$'
          nullable: true
          description: Stable account id used in the config key prefix. If omitted, the created party id is used.
          example: support
        displayName:
          type: string
          description: Human-readable account name.
          example: Acme Support Mail
        managementMode:
          allOf:
            - $ref: './software-manager-components.yml#/components/schemas/ManagementMode'
          default: EXTERNAL
          description: Email accounts are externally managed; the server rejects non-EXTERNAL values.
        runtimeMode:
          allOf:
            - $ref: './software-manager-components.yml#/components/schemas/RuntimeMode'
          nullable: true
          default: THIRD_PARTY
        config:
          $ref: '#/components/schemas/EmailAccountConfig'

    EmailAccountUpdateRequest:
      type: object
      description: Partial update request for a tenant email account.
      properties:
        config:
          $ref: '#/components/schemas/EmailAccountConfig'

    EmailAccountTestSendRequest:
      type: object
      description: Request to send a test message through a configured tenant email account.
      required: [to]
      properties:
        to:
          type: string
          format: email
          description: Recipient address for the test message.
          example: operator@acme.example
        subject:
          type: string
          nullable: true
          description: Optional subject. When omitted the server uses a VDX test-message subject.
          example: Test email from Acme Support
        textBody:
          type: string
          nullable: true
          description: Optional plain-text body. When omitted and `htmlBody` is also absent, a default test body is used.
        htmlBody:
          type: string
          nullable: true
          description: Optional HTML body.

    EmailAccountTestSendResponse:
      type: object
      description: Result returned after the test email has been accepted by the configured transport.
      required: [status, accountId]
      properties:
        status:
          type: string
          enum: [SENT]
          example: SENT
        accountId:
          type: string
          description: Stable email account id used for delivery.
          example: support
        deliveryId:
          type: string
          nullable: true
          description: Provider or transport message id when available.
        providerMessageId:
          type: string
          nullable: true
          description: Provider message id when available.
        transportId:
          type: string
          nullable: true
          description: Transport implementation that accepted the message.
          example: smtp

    EmailSoftwareConfigBinding:
      type: object
      description: Binding from the email software party/capability to its config key prefix.
      required: [id, tenantId, softwarePartyId, appId, profile, configScope, configKeyPrefix, bindingType, isActive]
      properties:
        id:
          type: string
          format: uuid
        tenantId:
          type: string
        softwarePartyId:
          type: string
          format: uuid
        capabilityId:
          type: string
          format: uuid
          nullable: true
        deploymentId:
          type: string
          format: uuid
          nullable: true
        appId:
          type: string
          example: vdx-service-email
        appVersion:
          type: string
          nullable: true
        profile:
          type: string
          example: default
        serviceId:
          type: string
          nullable: true
        configScope:
          type: string
          example: TENANT
        configScopeIdentifier:
          type: string
          nullable: true
        configKeyPrefix:
          type: string
          example: vdx.service.email.accounts.support
        bindingType:
          type: string
          example: email.account.smtp.v1
        isActive:
          type: boolean

    EmailAccountDetail:
      type: object
      description: Email account software-party detail.
      required:
        - partyId
        - tenantId
        - accountId
        - displayName
        - softwareKind
        - managementMode
        - capability
        - endpoints
        - credentials
        - createdAt
        - updatedAt
      properties:
        partyId:
          type: string
          format: uuid
        tenantId:
          type: string
        accountId:
          type: string
          description: Stable account id used below `vdx.service.email.accounts`.
          example: support
        displayName:
          type: string
          example: Acme Support Mail
        origin:
          type: string
          nullable: true
        softwareKind:
          $ref: './software-manager-components.yml#/components/schemas/SoftwareKind'
        managementMode:
          $ref: './software-manager-components.yml#/components/schemas/ManagementMode'
        runtimeMode:
          allOf:
            - $ref: './software-manager-components.yml#/components/schemas/RuntimeMode'
          nullable: true
        capability:
          type: object
          description: Software capability row for EMAIL_SERVER.
          additionalProperties: true
        config:
          allOf:
            - $ref: '#/components/schemas/EmailAccountConfig'
          nullable: true
        configBinding:
          allOf:
            - $ref: '#/components/schemas/EmailSoftwareConfigBinding'
          nullable: true
        endpoints:
          type: array
          items:
            type: object
            additionalProperties: true
        credentials:
          type: array
          items:
            type: object
            additionalProperties: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      example:
        partyId: 2e1e3ff6-6c3b-4f50-b97a-0c7ebd7c8c41
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        accountId: support
        displayName: Acme Support Mail
        softwareKind: SERVER
        managementMode: EXTERNAL
        runtimeMode: THIRD_PARTY
        capability:
          capabilityType: EMAIL_SERVER
          isEnabled: true
          lifecycleStatus: ACTIVE
        config:
          transportId: smtp
          fromAddress: support@acme.example
          fromName: Acme Support
          replyTo: helpdesk@acme.example
          smtp:
            host: smtp.mail.example
            port: 587
            username: support@acme.example
            useStarttls: true
            useSsl: false
        endpoints: []
        credentials: []
        createdAt: '2026-06-16T09:15:00Z'
        updatedAt: '2026-06-16T09:15:00Z'

    EmailAccountList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EmailAccountDetail'
        page:
          $ref: '#/components/schemas/PlatformConfigPageMeta'

    # ---- KMS providers (polymorphic by `type`) -------------------------------
    # A KMS provider is one of several backend types. The `type` field is the
    # discriminator; each type carries its own settings. `software` is the local
    # key store; `azure_keyvault` is Microsoft Azure Key Vault / Managed HSM.
    # Further types (e.g. AWS KMS) slot in under the same discriminator.

    KmsProviderType:
      type: string
      description: KMS provider type discriminator.
      enum: [software, azure_keyvault, aws_kms]

    KmsProviderRole:
      type: string
      description: >
        Runtime role of a KMS provider. `GENERAL` is customer/operator managed. Non-general roles are
        system-owned and protected; `_license_` is the license recipient KMS, `_platform_` is the
        platform authorization-server KMS, and `_tenant_` is the tenant root
        authorization-server KMS.
      enum: [GENERAL, LICENSE, PLATFORM_AUTHORIZATION_SERVER, TENANT_AUTHORIZATION_SERVER]

    KmsProviderCommon:
      type: object
      description: Fields shared by every KMS provider, regardless of type.
      required: [tenantId, providerId, type, enabled, system, role]
      properties:
        tenantId:
          type: string
          description: Tenant that owns the provider.
        providerId:
          type: string
          pattern: '^(_license_|_platform_|_tenant_|[a-z0-9][a-z0-9-]*)$'
          description: Identifier of the provider, unique within the tenant. `_license_`, `_platform_`, and `_tenant_` are reserved system ids.
        type:
          $ref: '#/components/schemas/KmsProviderType'
        enabled:
          type: boolean
          description: Whether the provider is currently active.
        system:
          type: boolean
          default: false
          description: >
            True for runtime-owned providers, which cannot be disabled or removed through tenant KMS
            administration.
        role:
          $ref: '#/components/schemas/KmsProviderRole'

    SoftwareKmsProvider:
      description: A software (local key store) KMS provider.
      allOf:
        - $ref: '#/components/schemas/KmsProviderCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [software]
            autoCreateCertificate:
              type: boolean
              default: false
              description: Whether the provider automatically creates a certificate for the keys it generates.
            keystoreType:
              type: string
              default: pkcs12
              example: pkcs12
              description: Key store format used by the software provider.
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        providerId: _tenant_
        type: software
        enabled: true
        system: true
        role: TENANT_AUTHORIZATION_SERVER
        autoCreateCertificate: true
        keystoreType: pkcs12

    AzureKeyVaultKmsProvider:
      description: >
        An Azure Key Vault (or Managed HSM) KMS provider. Authentication secrets are write-only and are
        never returned; the response reports only which credential mode is configured.
      allOf:
        - $ref: '#/components/schemas/KmsProviderCommon'
        - type: object
          required: [keyvaultUrl, azureTenantId, hsmType, credentialMode]
          properties:
            type:
              type: string
              enum: [azure_keyvault]
            keyvaultUrl:
              type: string
              format: uri
              description: Base URL of the Azure Key Vault or Managed HSM instance.
              example: https://acme-kv.vault.azure.net/
            azureTenantId:
              type: string
              description: Microsoft Entra (Azure AD) directory tenant ID the vault belongs to. Distinct from the platform tenant in the path.
              example: 72f988bf-86f1-41af-91ab-2d7cd011db47
            applicationId:
              type: string
              description: Microsoft Entra application (client) ID used to access the vault.
              example: azure-keyvault
            hsmType:
              $ref: '#/components/schemas/AzureHsmType'
            credentialMode:
              $ref: '#/components/schemas/AzureCredentialMode'
            exponentialBackoffRetry:
              $ref: '#/components/schemas/KmsExponentialBackoffRetry'
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        providerId: acme-azure
        type: azure_keyvault
        enabled: true
        system: false
        role: GENERAL
        keyvaultUrl: https://acme-kv.vault.azure.net/
        azureTenantId: 72f988bf-86f1-41af-91ab-2d7cd011db47
        applicationId: 11112222-3333-4444-5555-666677778888
        hsmType: KEYVAULT
        credentialMode: SERVICE_CLIENT_SECRET

    AwsKmsProvider:
      description: >
        An AWS KMS provider. Authentication secrets are write-only and are never returned; the response
        reports only which credential mode is configured.
      allOf:
        - $ref: '#/components/schemas/KmsProviderCommon'
        - type: object
          required: [region, credentialMode]
          properties:
            type:
              type: string
              enum: [aws_kms]
            region:
              type: string
              description: AWS region the KMS keys live in.
              example: eu-west-1
            applicationId:
              type: string
              description: Application identifier label for the AWS KMS client.
              example: aws-kms
            credentialMode:
              $ref: '#/components/schemas/AwsCredentialMode'
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        providerId: acme-aws
        type: aws_kms
        enabled: true
        system: false
        role: GENERAL
        region: eu-west-1
        applicationId: aws-kms
        credentialMode: ACCESS_KEY

    KmsProvider:
      description: A KMS provider configured for a tenant. The concrete shape is selected by `type`.
      oneOf:
        - $ref: '#/components/schemas/SoftwareKmsProvider'
        - $ref: '#/components/schemas/AzureKeyVaultKmsProvider'
        - $ref: '#/components/schemas/AwsKmsProvider'
      discriminator:
        propertyName: type
        mapping:
          software: '#/components/schemas/SoftwareKmsProvider'
          azure_keyvault: '#/components/schemas/AzureKeyVaultKmsProvider'
          aws_kms: '#/components/schemas/AwsKmsProvider'

    KmsProviderList:
      type: object
      description: A tenant's KMS providers.
      required: [providers]
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/KmsProvider'

    AzureHsmType:
      type: string
      description: Azure Key Vault implementation type.
      enum: [KEYVAULT, MANAGED_HSM]

    AzureCredentialMode:
      type: string
      description: How the provider authenticates to Azure.
      enum:
        - SERVICE_CLIENT_SECRET
        - SERVICE_CLIENT_CERTIFICATE
        - USER_INTERACTIVE_BROWSER
        - USER_USERNAME_PASSWORD

    KmsExponentialBackoffRetry:
      type: object
      description: Exponential-backoff retry policy for Key Vault requests.
      properties:
        maxRetries:
          type: integer
          default: 10
        baseDelayInMs:
          type: integer
          format: int64
          default: 1000
        maxDelayInMs:
          type: integer
          format: int64
          default: 15000

    AzureSecretCredentialOpts:
      type: object
      description: Client-secret authentication.
      required: [clientId, clientSecret]
      properties:
        clientId:
          type: string
        clientSecret:
          type: string
          writeOnly: true
          description: >
            Resolvable reference to the client secret — `${secret:<logical-key>[:<key>]}` or `${env:NAME}`.
            A plaintext secret is rejected; never returned.

    AzureCertificateCredentialOpts:
      type: object
      description: Client-certificate authentication.
      required: [clientId, pemCertificatePath]
      properties:
        clientId:
          type: string
        pemCertificatePath:
          type: string
          description: Path to the PEM certificate available to the deployment.

    AzureInteractiveBrowserCredentialOpts:
      type: object
      description: Interactive-browser authentication.
      required: [clientId, redirectUrl]
      properties:
        clientId:
          type: string
        redirectUrl:
          type: string
          format: uri

    AzureUsernamePasswordCredentialOpts:
      type: object
      description: Username/password authentication.
      required: [clientId, userName, password]
      properties:
        clientId:
          type: string
        userName:
          type: string
        password:
          type: string
          writeOnly: true
          description: >
            Resolvable reference to the password — `${secret:<logical-key>[:<key>]}` or `${env:NAME}`.
            A plaintext value is rejected; never returned.

    AzureCredentialOpts:
      type: object
      description: >
        Azure authentication options. Provide exactly the option block that matches `credentialMode`.
      required: [credentialMode]
      properties:
        credentialMode:
          $ref: '#/components/schemas/AzureCredentialMode'
        secretCredentialOpts:
          $ref: '#/components/schemas/AzureSecretCredentialOpts'
        certificateCredentialOpts:
          $ref: '#/components/schemas/AzureCertificateCredentialOpts'
        interactiveBrowserCredentialOpts:
          $ref: '#/components/schemas/AzureInteractiveBrowserCredentialOpts'
        usernamePasswordCredentialOpts:
          $ref: '#/components/schemas/AzureUsernamePasswordCredentialOpts'

    AwsCredentialMode:
      type: string
      description: How the provider authenticates to AWS.
      enum: [ACCESS_KEY, PROFILE, CONTAINER, INSTANCE]

    AwsAccessKeyCredentialOpts:
      type: object
      description: Static access-key authentication.
      required: [accessKeyId, secretAccessKey]
      properties:
        accessKeyId:
          type: string
        secretAccessKey:
          type: string
          writeOnly: true
          description: >
            Resolvable reference to the secret access key — `${secret:<logical-key>[:<key>]}` or
            `${env:NAME}`. A plaintext secret is rejected; never returned.
        sessionToken:
          type: string
          writeOnly: true
          description: Optional reference to a temporary session token (same reference rules as the secret access key).

    AwsProfileCredentialOpts:
      type: object
      description: Named shared-config profile authentication.
      required: [profileName]
      properties:
        profileName:
          type: string

    AwsCredentialOpts:
      type: object
      description: >
        AWS authentication options. Provide the option block that matches `credentialMode`; `CONTAINER`
        and `INSTANCE` source credentials from the runtime environment and need no block.
      required: [credentialMode]
      properties:
        credentialMode:
          $ref: '#/components/schemas/AwsCredentialMode'
        accessKeyCredentialOpts:
          $ref: '#/components/schemas/AwsAccessKeyCredentialOpts'
        profileCredentialOpts:
          $ref: '#/components/schemas/AwsProfileCredentialOpts'

    CreateKmsProviderRequestCommon:
      type: object
      required: [providerId]
      properties:
        providerId:
          type: string
          pattern: '^[a-z0-9][a-z0-9-]*$'
          description: Identifier for the new provider, unique within the tenant. Reserved system ids such as `_tenant_`, `_platform_`, and `_license_` cannot be used.
        type:
          $ref: '#/components/schemas/KmsProviderType'

    CreateSoftwareKmsProviderRequest:
      description: Request to add a software (local key store) KMS provider.
      allOf:
        - $ref: '#/components/schemas/CreateKmsProviderRequestCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [software]
              default: software
            autoCreateCertificate:
              type: boolean
              default: true
              description: Whether the provider automatically creates a certificate for the keys it generates.
            keystoreType:
              type: string
              default: pkcs12
              description: Key store format for the software provider.
      example:
        providerId: acme-secondary
        type: software
        autoCreateCertificate: true

    CreateAzureKeyVaultKmsProviderRequest:
      description: Request to add an Azure Key Vault (or Managed HSM) KMS provider.
      allOf:
        - $ref: '#/components/schemas/CreateKmsProviderRequestCommon'
        - type: object
          required: [keyvaultUrl, azureTenantId, hsmType, credentialOpts]
          properties:
            type:
              type: string
              enum: [azure_keyvault]
            keyvaultUrl:
              type: string
              format: uri
              description: Base URL of the Azure Key Vault or Managed HSM instance.
            azureTenantId:
              type: string
              description: Microsoft Entra (Azure AD) directory tenant ID the vault belongs to.
            applicationId:
              type: string
              description: Microsoft Entra application (client) ID used to access the vault.
            hsmType:
              $ref: '#/components/schemas/AzureHsmType'
            credentialOpts:
              $ref: '#/components/schemas/AzureCredentialOpts'
            exponentialBackoffRetry:
              $ref: '#/components/schemas/KmsExponentialBackoffRetry'
      example:
        providerId: acme-azure
        type: azure_keyvault
        keyvaultUrl: https://acme-kv.vault.azure.net/
        azureTenantId: 72f988bf-86f1-41af-91ab-2d7cd011db47
        applicationId: 11112222-3333-4444-5555-666677778888
        hsmType: KEYVAULT
        credentialOpts:
          credentialMode: SERVICE_CLIENT_SECRET
          secretCredentialOpts:
            clientId: 11112222-3333-4444-5555-666677778888
            clientSecret: ${env:ACME_AZURE_CLIENT_SECRET}

    CreateAwsKmsProviderRequest:
      description: Request to add an AWS KMS provider.
      allOf:
        - $ref: '#/components/schemas/CreateKmsProviderRequestCommon'
        - type: object
          required: [region, credentialOpts]
          properties:
            type:
              type: string
              enum: [aws_kms]
            region:
              type: string
              description: AWS region the KMS keys live in.
            applicationId:
              type: string
              description: Application identifier label for the AWS KMS client.
            credentialOpts:
              $ref: '#/components/schemas/AwsCredentialOpts'
            exponentialBackoffRetry:
              $ref: '#/components/schemas/KmsExponentialBackoffRetry'
      example:
        providerId: acme-aws
        type: aws_kms
        region: eu-west-1
        credentialOpts:
          credentialMode: ACCESS_KEY
          accessKeyCredentialOpts:
            accessKeyId: AKIAEXAMPLE
            secretAccessKey: ${env:ACME_AWS_SECRET}

    CreateKmsProviderRequest:
      description: Request to add a KMS provider. The concrete shape is selected by `type`.
      oneOf:
        - $ref: '#/components/schemas/CreateSoftwareKmsProviderRequest'
        - $ref: '#/components/schemas/CreateAzureKeyVaultKmsProviderRequest'
        - $ref: '#/components/schemas/CreateAwsKmsProviderRequest'
      discriminator:
        propertyName: type
        mapping:
          software: '#/components/schemas/CreateSoftwareKmsProviderRequest'
          azure_keyvault: '#/components/schemas/CreateAzureKeyVaultKmsProviderRequest'
          aws_kms: '#/components/schemas/CreateAwsKmsProviderRequest'

    UpdateKmsProviderRequestCommon:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/KmsProviderType'
        enabled:
          type: boolean
          description: Whether the provider is active.

    UpdateSoftwareKmsProviderRequest:
      description: Partial update of a software KMS provider. Omitted fields are left unchanged.
      allOf:
        - $ref: '#/components/schemas/UpdateKmsProviderRequestCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [software]
            autoCreateCertificate:
              type: boolean
              description: Whether the provider automatically creates a certificate for the keys it generates.

    UpdateAzureKeyVaultKmsProviderRequest:
      description: >
        Partial update of an Azure KMS provider. Supplying `credentialOpts` rotates the credentials
        (the previous credential block is replaced).
      allOf:
        - $ref: '#/components/schemas/UpdateKmsProviderRequestCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [azure_keyvault]
            keyvaultUrl:
              type: string
              format: uri
            azureTenantId:
              type: string
            applicationId:
              type: string
            hsmType:
              $ref: '#/components/schemas/AzureHsmType'
            credentialOpts:
              $ref: '#/components/schemas/AzureCredentialOpts'

    UpdateAwsKmsProviderRequest:
      description: >
        Partial update of an AWS KMS provider. Supplying `credentialOpts` rotates the credentials
        (the previous credential block is replaced).
      allOf:
        - $ref: '#/components/schemas/UpdateKmsProviderRequestCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [aws_kms]
            region:
              type: string
            applicationId:
              type: string
            credentialOpts:
              $ref: '#/components/schemas/AwsCredentialOpts'

    UpdateKmsProviderRequest:
      description: Partial update of a KMS provider's mutable settings. The concrete shape is selected by `type`.
      oneOf:
        - $ref: '#/components/schemas/UpdateSoftwareKmsProviderRequest'
        - $ref: '#/components/schemas/UpdateAzureKeyVaultKmsProviderRequest'
        - $ref: '#/components/schemas/UpdateAwsKmsProviderRequest'
      discriminator:
        propertyName: type
        mapping:
          software: '#/components/schemas/UpdateSoftwareKmsProviderRequest'
          azure_keyvault: '#/components/schemas/UpdateAzureKeyVaultKmsProviderRequest'
          aws_kms: '#/components/schemas/UpdateAwsKmsProviderRequest'
    EnableKmsProviderRequest:
      type: object
      description: Enable or disable a KMS provider. The tenant's primary provider cannot be disabled.
      required: [enabled]
      properties:
        enabled:
          type: boolean
          description: Target state — `true` to enable, `false` to disable.
      example:
        enabled: true

    # =====================================================================
    # Secret providers
    # =====================================================================
    SecretProviderType:
      type: string
      description: >
        Secret provider type discriminator. `vault`, `azure`, and `aws` are writable. `kubernetes-mount`
        is read-only. The `env` provider is the implicit read-only floor and is never selected through
        this surface.
      enum: [vault, azure, aws, kubernetes-mount]

    SecretPartitionStrategy:
      type: string
      description: >
        How tenant and instance addresses are sharded into a physical, backend-native address. When
        omitted on a write, the per-type default applies (`vault` and `kubernetes-mount` default to
        `TENANT_PATH_INSTANCE_PATH`; `azure` and `aws` default to `TENANT_LABEL_INSTANCE_PREFIX`).
      enum:
        - TENANT_PATH_INSTANCE_PATH
        - TENANT_LABEL_INSTANCE_PREFIX
        - DEDICATED_BACKEND
        - GLOBAL

    SecretProviderCommon:
      type: object
      description: Fields shared by every secret provider read view, regardless of type.
      required: [tenantId, type, enabled]
      properties:
        tenantId:
          type: string
          description: Tenant the provider is selected for.
        type:
          $ref: '#/components/schemas/SecretProviderType'
        enabled:
          type: boolean
          description: >
            Whether this provider type is enabled as a deployment capability for the scope.
            Informational on the read view; the selection itself is the tenant's `secrets.provider.type`.
        partitionStrategy:
          allOf:
            - $ref: '#/components/schemas/SecretPartitionStrategy'
          description: Effective partition strategy applied when sharding addresses.
        instanceId:
          type: string
          nullable: true
          description: Instance id folded into the address shard, when one is configured.

    VaultSecretProvider:
      description: A HashiCorp Vault (or compatible) secret provider.
      allOf:
        - $ref: '#/components/schemas/SecretProviderCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [vault]
            address:
              type: string
              format: uri
              description: Base URL of the Vault server.
              example: https://vault.acme.internal
            mount:
              type: string
              description: KV mount path the provider reads and writes under.
              example: secret
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        type: vault
        enabled: true
        partitionStrategy: TENANT_PATH_INSTANCE_PATH
        instanceId: null
        address: https://vault.acme.internal
        mount: secret

    AzureSecretProvider:
      description: >
        An Azure Key Vault secret provider. Authentication secrets are write-only and are never returned;
        the response reports only which credential mode is configured.
      allOf:
        - $ref: '#/components/schemas/SecretProviderCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [azure]
            keyvaultUrl:
              type: string
              format: uri
              description: Base URL of the Azure Key Vault instance.
              example: https://acme-secrets.vault.azure.net/
            azureTenantId:
              type: string
              description: Microsoft Entra (Azure AD) directory tenant ID the vault belongs to.
            credentialMode:
              $ref: '#/components/schemas/AzureCredentialMode'
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        type: azure
        enabled: true
        partitionStrategy: TENANT_LABEL_INSTANCE_PREFIX
        keyvaultUrl: https://acme-secrets.vault.azure.net/
        azureTenantId: 72f988bf-86f1-41af-91ab-2d7cd011db47
        credentialMode: SERVICE_CLIENT_SECRET

    AwsSecretProvider:
      description: >
        An AWS Secrets Manager secret provider. Authentication secrets are write-only and are never
        returned; the response reports only which credential mode is configured.
      allOf:
        - $ref: '#/components/schemas/SecretProviderCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [aws]
            region:
              type: string
              description: AWS region the secrets live in.
              example: eu-west-1
            credentialMode:
              $ref: '#/components/schemas/AwsCredentialMode'
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        type: aws
        enabled: true
        partitionStrategy: TENANT_LABEL_INSTANCE_PREFIX
        region: eu-west-1
        credentialMode: ACCESS_KEY

    KubernetesMountSecretProvider:
      description: >
        A Kubernetes secret-mount provider. This provider is read-only; secret values are projected into
        the deployment by Kubernetes and cannot be written through this surface.
      allOf:
        - $ref: '#/components/schemas/SecretProviderCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [kubernetes-mount]
            mountPath:
              type: string
              description: Filesystem path the secrets are projected to.
              example: /var/run/secrets/sphereon
      example:
        tenantId: 7b3c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        type: kubernetes-mount
        enabled: true
        partitionStrategy: TENANT_PATH_INSTANCE_PATH
        mountPath: /var/run/secrets/sphereon

    SecretProvider:
      description: >
        The secret provider selected for a tenant. The concrete shape is selected by `type`. Plaintext
        secrets and credential references are never present.
      oneOf:
        - $ref: '#/components/schemas/VaultSecretProvider'
        - $ref: '#/components/schemas/AzureSecretProvider'
        - $ref: '#/components/schemas/AwsSecretProvider'
        - $ref: '#/components/schemas/KubernetesMountSecretProvider'
      discriminator:
        propertyName: type
        mapping:
          vault: '#/components/schemas/VaultSecretProvider'
          azure: '#/components/schemas/AzureSecretProvider'
          aws: '#/components/schemas/AwsSecretProvider'
          kubernetes-mount: '#/components/schemas/KubernetesMountSecretProvider'

    SetSecretProviderRequestCommon:
      type: object
      required: [type]
      properties:
        type:
          $ref: '#/components/schemas/SecretProviderType'
        partitionStrategy:
          allOf:
            - $ref: '#/components/schemas/SecretPartitionStrategy'
          description: Address sharding strategy. Omit to apply the per-type default.
        instanceId:
          type: string
          description: Optional instance id folded into the address shard.

    SetVaultSecretProviderRequest:
      description: Select and configure a HashiCorp Vault (or compatible) secret provider.
      allOf:
        - $ref: '#/components/schemas/SetSecretProviderRequestCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [vault]
            address:
              type: string
              format: uri
              description: Base URL of the Vault server.
            mount:
              type: string
              description: KV mount path to read and write under.
            credentialRef:
              allOf:
                - $ref: '#/components/schemas/SecretReference'
              description: >
                Reference to the Vault token or auth secret, resolved at runtime. A plaintext secret is
                rejected; never returned.
      example:
        type: vault
        partitionStrategy: TENANT_PATH_INSTANCE_PATH
        address: https://vault.acme.internal
        mount: secret
        credentialRef:
          ref: ${env:ACME_VAULT_TOKEN}

    SetAzureSecretProviderRequest:
      description: Select and configure an Azure Key Vault secret provider.
      allOf:
        - $ref: '#/components/schemas/SetSecretProviderRequestCommon'
        - type: object
          required: [keyvaultUrl, azureTenantId, credentialOpts]
          properties:
            type:
              type: string
              enum: [azure]
            keyvaultUrl:
              type: string
              format: uri
              description: Base URL of the Azure Key Vault instance.
            azureTenantId:
              type: string
              description: Microsoft Entra (Azure AD) directory tenant ID the vault belongs to.
            applicationId:
              type: string
              description: Optional application/instance id folded into this provider's configuration.
            credentialOpts:
              $ref: '#/components/schemas/AzureCredentialOpts'
      example:
        type: azure
        keyvaultUrl: https://acme-secrets.vault.azure.net/
        azureTenantId: 72f988bf-86f1-41af-91ab-2d7cd011db47
        credentialOpts:
          credentialMode: SERVICE_CLIENT_SECRET
          secretCredentialOpts:
            clientId: 11112222-3333-4444-5555-666677778888
            clientSecret: ${env:ACME_AZURE_SECRETS_CLIENT_SECRET}

    SetAwsSecretProviderRequest:
      description: Select and configure an AWS Secrets Manager secret provider.
      allOf:
        - $ref: '#/components/schemas/SetSecretProviderRequestCommon'
        - type: object
          required: [region, credentialOpts]
          properties:
            type:
              type: string
              enum: [aws]
            region:
              type: string
              description: AWS region the secrets live in.
            applicationId:
              type: string
              description: Optional application/instance id folded into this provider's configuration.
            credentialOpts:
              $ref: '#/components/schemas/AwsCredentialOpts'
      example:
        type: aws
        region: eu-west-1
        credentialOpts:
          credentialMode: ACCESS_KEY
          accessKeyCredentialOpts:
            accessKeyId: AKIAEXAMPLE
            secretAccessKey: ${env:ACME_AWS_SECRETS_SECRET}

    SetKubernetesMountSecretProviderRequest:
      description: >
        Select a Kubernetes secret-mount provider. The provider is read-only; no credentials are accepted
        and secret values cannot be written through this surface.
      allOf:
        - $ref: '#/components/schemas/SetSecretProviderRequestCommon'
        - type: object
          properties:
            type:
              type: string
              enum: [kubernetes-mount]
            mountPath:
              type: string
              description: Filesystem path the secrets are projected to.
      example:
        type: kubernetes-mount
        mountPath: /var/run/secrets/sphereon

    SetSecretProviderRequest:
      description: >
        Select and configure the tenant's secret provider. The concrete shape is selected by `type`.
        Credentials are supplied as references and are never returned.
      oneOf:
        - $ref: '#/components/schemas/SetVaultSecretProviderRequest'
        - $ref: '#/components/schemas/SetAzureSecretProviderRequest'
        - $ref: '#/components/schemas/SetAwsSecretProviderRequest'
        - $ref: '#/components/schemas/SetKubernetesMountSecretProviderRequest'
      discriminator:
        propertyName: type
        mapping:
          vault: '#/components/schemas/SetVaultSecretProviderRequest'
          azure: '#/components/schemas/SetAzureSecretProviderRequest'
          aws: '#/components/schemas/SetAwsSecretProviderRequest'
          kubernetes-mount: '#/components/schemas/SetKubernetesMountSecretProviderRequest'

    SecretValuesWriteRequest:
      type: object
      description: >
        One or more secret values to write through the tenant's selected writable provider, keyed by
        logical secret key. Values are write-only and never returned.
      required: [values]
      properties:
        values:
          type: object
          additionalProperties:
            type: string
            writeOnly: true
          description: Map of logical secret key to plaintext value. The provider must be writable.
      example:
        values:
          idp/idp-client-secret: super-secret-value

    SecretValuesWriteResult:
      type: object
      description: Canonical secret references for the written values, keyed by the same logical secret keys.
      required: [references]
      properties:
        references:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SecretReference'
          description: Map of logical secret key to its canonical reference.
      example:
        references:
          idp/idp-client-secret:
            ref: ${secret:idp/idp-client-secret}

    AsTokensConfig:
      type: object
      description: Plain write shape for token lifetimes and token behavior. PUT omits or nulls clear tenant-set values back to defaults.
      properties:
        accessTokenLifetimeSeconds:
          type: integer
          format: int64
          minimum: 1
          description: Access token lifetime in seconds.
        refreshTokenLifetimeSeconds:
          type: integer
          format: int64
          minimum: 1
          nullable: true
          description: Refresh token lifetime in seconds.
        authorizationCodeLifetimeSeconds:
          type: integer
          format: int64
          minimum: 1
          description: Authorization code lifetime in seconds.
        idTokenLifetimeSeconds:
          type: integer
          format: int64
          minimum: 1
          description: ID token lifetime in seconds.
        tokenFormat:
          type: string
          description: Access token representation emitted by the AS runtime.
          example: jwt
        refreshTokenRotation:
          type: boolean
          description: Rotates refresh tokens on use when true.
      example:
        accessTokenLifetimeSeconds: 3600
        refreshTokenLifetimeSeconds: 2592000
        authorizationCodeLifetimeSeconds: 300
        idTokenLifetimeSeconds: 3600
        tokenFormat: jwt
        refreshTokenRotation: true
    AsTokensConfigView:
      type: object
      required: [accessTokenLifetimeSeconds, refreshTokenLifetimeSeconds, authorizationCodeLifetimeSeconds, idTokenLifetimeSeconds, tokenFormat, refreshTokenRotation]
      properties:
        accessTokenLifetimeSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
        refreshTokenLifetimeSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
        authorizationCodeLifetimeSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
        idTokenLifetimeSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
        tokenFormat:
          $ref: '#/components/schemas/StringConfigField'
        refreshTokenRotation:
          $ref: '#/components/schemas/BooleanConfigField'
      example:
        accessTokenLifetimeSeconds: { value: 1800, source: tenant }
        refreshTokenLifetimeSeconds: { value: 2592000, source: default }
        authorizationCodeLifetimeSeconds: { value: 300, source: default }
        idTokenLifetimeSeconds: { value: 3600, source: default }
        tokenFormat: { value: jwt, source: tenant }
        refreshTokenRotation: { value: true, source: default }
    AsGrantsConfig:
      type: object
      description: Enabled grant types, response types, and scopes. `code` responses require `authorization_code`; token response types require `implicit`.
      properties:
        grantTypesEnabled:
          type: array
          description: OAuth2 grant types enabled for the authorization server.
          items:
            type: string
        responseTypesSupported:
          type: array
          description: OAuth2/OIDC response types advertised by the authorization server.
          items:
            type: string
        scopesSupported:
          type: array
          description: OAuth2 scopes advertised by the authorization server.
          items:
            type: string
      example:
        grantTypesEnabled: [authorization_code, refresh_token]
        responseTypesSupported: [code]
        scopesSupported: [openid, profile, email]
    AsGrantsConfigView:
      type: object
      required: [grantTypesEnabled, responseTypesSupported, scopesSupported]
      properties:
        grantTypesEnabled:
          $ref: '#/components/schemas/StringListConfigField'
        responseTypesSupported:
          $ref: '#/components/schemas/StringListConfigField'
        scopesSupported:
          $ref: '#/components/schemas/StringListConfigField'
    AsFeaturesConfig:
      type: object
      description: Typed OAuth2/OIDC feature policy for the authorization server.
      additionalProperties: false
      properties:
        oidc:
          $ref: '#/components/schemas/FeatureMode'
        logout:
          $ref: '#/components/schemas/FeatureMode'
        introspection:
          $ref: '#/components/schemas/FeatureMode'
        revocation:
          $ref: '#/components/schemas/FeatureMode'
        par:
          $ref: '#/components/schemas/FeatureMode'
        tokenExchange:
          $ref: '#/components/schemas/FeatureMode'
        deviceFlow:
          $ref: '#/components/schemas/FeatureMode'
        pkce:
          $ref: '#/components/schemas/FeatureMode'
        dpop:
          $ref: '#/components/schemas/FeatureMode'
        iae:
          $ref: '#/components/schemas/FeatureMode'
        jar:
          $ref: '#/components/schemas/FeatureMode'
        attestation:
          $ref: '#/components/schemas/FeatureMode'
        jarm:
          $ref: '#/components/schemas/FeatureMode'
        mtls:
          $ref: '#/components/schemas/FeatureMode'
        signedMetadata:
          $ref: '#/components/schemas/FeatureMode'
      example:
        oidc: supported
        logout: supported
        introspection: supported
        revocation: supported
        par: disabled
        tokenExchange: disabled
        deviceFlow: disabled
        pkce: required
        dpop: supported
        iae: disabled
        jar: supported
        attestation: disabled
        jarm: disabled
        mtls: disabled
        signedMetadata: supported
    AsFeaturesConfigView:
      type: object
      description: Effective typed OAuth2/OIDC feature policy with source markers.
      required: [oidc, logout, introspection, revocation, par, tokenExchange, deviceFlow, pkce, dpop, iae, jar, attestation, jarm, mtls, signedMetadata]
      additionalProperties: false
      properties:
        oidc:
          $ref: '#/components/schemas/FeatureConfigField'
        logout:
          $ref: '#/components/schemas/FeatureConfigField'
        introspection:
          $ref: '#/components/schemas/FeatureConfigField'
        revocation:
          $ref: '#/components/schemas/FeatureConfigField'
        par:
          $ref: '#/components/schemas/FeatureConfigField'
        tokenExchange:
          $ref: '#/components/schemas/FeatureConfigField'
        deviceFlow:
          $ref: '#/components/schemas/FeatureConfigField'
        pkce:
          $ref: '#/components/schemas/FeatureConfigField'
        dpop:
          $ref: '#/components/schemas/FeatureConfigField'
        iae:
          $ref: '#/components/schemas/FeatureConfigField'
        jar:
          $ref: '#/components/schemas/FeatureConfigField'
        attestation:
          $ref: '#/components/schemas/FeatureConfigField'
        jarm:
          $ref: '#/components/schemas/FeatureConfigField'
        mtls:
          $ref: '#/components/schemas/FeatureConfigField'
        signedMetadata:
          $ref: '#/components/schemas/FeatureConfigField'
      example:
        oidc: { value: supported, source: default }
        logout: { value: supported, source: default }
        introspection: { value: supported, source: default }
        revocation: { value: supported, source: default }
        par: { value: disabled, source: tenant }
        tokenExchange: { value: disabled, source: tenant }
        deviceFlow: { value: disabled, source: tenant }
        pkce: { value: required, source: tenant }
        dpop: { value: supported, source: tenant }
        iae: { value: disabled, source: tenant }
        jar: { value: supported, source: default }
        attestation: { value: disabled, source: tenant }
        jarm: { value: disabled, source: tenant }
        mtls: { value: disabled, source: tenant }
        signedMetadata: { value: supported, source: default }
    AsClientType:
      type: string
      description: OAuth2 client class consumed by the AS runtime.
      enum: [public, confidential]
      example: public
    AsClientAuthMethod:
      type: string
      description: OAuth2 token endpoint authentication method for this client.
      enum:
        - none
        - client_secret_basic
        - client_secret_post
        - private_key_jwt
        - client_secret_jwt
        - tls_client_auth
        - self_signed_tls_client_auth
        - attest_jwt_client_auth
      example: client_secret_basic
    AsClientBase:
      type: object
      description: >
        OAuth2 client registration consumed by the AS runtime from
        AS-scoped tenant config keys. The REST path determines whether the
        client belongs to the tenant's singleton AS or to an instance-scoped AS.
        Public and confidential clients use the same object shape and are
        differentiated by `clientType`.
      properties:
        clientId:
          type: string
          description: Stable OAuth2 client identifier.
          example: wallet-web
        clientName:
          type: string
          nullable: true
          description: Human-readable client name.
          example: Acme web wallet
        clientType:
          $ref: '#/components/schemas/AsClientType'
        enabled:
          type: boolean
          default: true
          description: Enables the client registration for runtime use.
        grantTypes:
          type: array
          items:
            type: string
          description: OAuth2 grant types enabled for this client.
          example: [authorization_code, refresh_token]
        responseTypes:
          type: array
          items:
            type: string
          description: OAuth2/OIDC response types allowed for this client.
          example: [code]
        redirectUris:
          type: array
          items:
            type: string
            format: uri
          description: Redirect URIs accepted for authorization responses.
          example: [https://wallet.acme.example/callback]
        allowedScopes:
          type: array
          items:
            type: string
            example: openid
          nullable: true
          description: Scopes this client may request. Null inherits the AS policy.
          example: [openid, profile, email]
        tokenEndpointAuthMethod:
          $ref: '#/components/schemas/AsClientAuthMethod'
        jwksUri:
          type: string
          format: uri
          nullable: true
          description: Client JWKS URI used for private-key JWT or signed request-object validation.
          example: https://issuer.acme.example/oauth2/jwks.json
        requirePkce:
          type: boolean
          nullable: true
          description: Requires PKCE for authorization code flows.
        requirePushedAuthorizationRequests:
          type: boolean
          nullable: true
          description: Requires pushed authorization requests for this client.
        dpopBoundAccessTokens:
          type: boolean
          nullable: true
          description: Issues DPoP-bound access tokens for this client.
        accessTokenLifetime:
          type: integer
          minimum: 1
          nullable: true
          description: Client-specific access token lifetime in seconds.
        refreshTokenLifetime:
          type: integer
          minimum: 1
          nullable: true
          description: Client-specific refresh token lifetime in seconds.
        authorizationCodeLifetime:
          type: integer
          minimum: 1
          nullable: true
          description: Client-specific authorization code lifetime in seconds.
        trustedAttesterIssuers:
          type: array
          items:
            type: string
            example: https://wallet-provider.example
          nullable: true
          description: Trusted attestation issuers for wallet or client attestation.
          example: [https://wallet-provider.example]
        trustedAttesterJwksUris:
          type: array
          items:
            type: string
            format: uri
          nullable: true
          description: JWKS URIs used to validate trusted attestation issuers.
          example: [https://wallet-provider.example/jwks.json]
        postLogoutRedirectUris:
          type: array
          items:
            type: string
            format: uri
          description: Redirect URIs accepted after RP-initiated logout.
          example: [https://wallet.acme.example/logout/callback]
        frontchannelLogoutUri:
          type: string
          format: uri
          nullable: true
          description: Front-channel logout URI registered for this client.
          example: https://wallet.acme.example/logout/frontchannel
        frontchannelLogoutSessionRequired:
          type: boolean
          nullable: true
          description: Indicates whether front-channel logout requires a session identifier.
        backchannelLogoutUri:
          type: string
          format: uri
          nullable: true
          description: Back-channel logout URI registered for this client.
          example: https://wallet.acme.example/logout/backchannel
        backchannelLogoutSessionRequired:
          type: boolean
          nullable: true
          description: Indicates whether back-channel logout requires a session identifier.
        authorizationSignedResponseAlg:
          type: string
          nullable: true
          description: JARM signing algorithm for authorization responses.
          example: ES256
        authorizationEncryptedResponseAlg:
          type: string
          nullable: true
          description: JARM key-management algorithm for encrypted authorization responses.
          example: ECDH-ES
        authorizationEncryptedResponseEnc:
          type: string
          nullable: true
          description: JARM content-encryption algorithm for encrypted authorization responses.
          example: A256GCM
        requestObjectSigningAlg:
          type: string
          nullable: true
          description: Required signing algorithm for request objects submitted by this client.
          example: ES256
        requestUris:
          type: array
          items:
            type: string
            format: uri
          description: Pre-registered request object URIs accepted for this client.
          example: [https://wallet.acme.example/oauth/request.jwt]
        tlsClientAuthSubjectDn:
          type: string
          nullable: true
          description: Subject distinguished name accepted for TLS client authentication.
          example: CN=issuer-backend,O=Acme Corp,C=NL
        tlsClientAuthSanDns:
          type: string
          nullable: true
          description: DNS SAN accepted for TLS client authentication.
          example: issuer-backend.acme.example
        tlsClientAuthSanEmail:
          type: string
          nullable: true
          description: Email SAN accepted for TLS client authentication.
          example: oauth-client@acme.example
        tlsClientAuthSanIp:
          type: string
          nullable: true
          description: IP address SAN accepted for TLS client authentication.
          example: 203.0.113.10
        tlsClientAuthSanUri:
          type: string
          nullable: true
          description: URI SAN accepted for TLS client authentication.
          example: spiffe://acme.example/oauth/issuer-backend
        tlsClientCertificateBoundAccessTokens:
          type: boolean
          nullable: true
          description: Binds issued access tokens to the client's TLS certificate.
    AsClient:
      allOf:
        - $ref: '#/components/schemas/AsClientBase'
        - type: object
          required: [clientId, clientType, enabled, grantTypes, tokenEndpointAuthMethod, clientSecretConfigured]
          properties:
            clientSecretConfigured:
              type: boolean
              description: True when a confidential client secret is configured. The secret value is never returned.
      example:
        clientId: wallet-web
        clientName: Acme web wallet
        clientType: public
        enabled: true
        grantTypes: [authorization_code, refresh_token]
        responseTypes: [code]
        redirectUris: [https://wallet.acme.example/callback]
        allowedScopes: [openid, profile, email]
        tokenEndpointAuthMethod: none
        requirePkce: true
        clientSecretConfigured: false
    AsClientCreateRequest:
      allOf:
        - $ref: '#/components/schemas/AsClientBase'
        - type: object
          required: [clientId, clientType, grantTypes]
          properties:
            clientSecret:
              type: string
              writeOnly: true
              description: Secret to store for confidential clients using client-secret authentication. Never returned.
      example:
        clientId: issuer-backend
        clientName: Issuer backend
        clientType: confidential
        clientSecret: 8m3YwWv7qR4p2sL9nT6x
        grantTypes: [client_credentials]
        tokenEndpointAuthMethod: client_secret_basic
        allowedScopes: [issuance]
    AsClientReplaceRequest:
      allOf:
        - $ref: '#/components/schemas/AsClientCreateRequest'
      description: Full replacement request. Omitted nullable fields are cleared.
    AsClientPatchRequest:
      allOf:
        - $ref: '#/components/schemas/AsClientBase'
        - type: object
          properties:
            clientSecret:
              type: string
              writeOnly: true
              description: Replacement client secret. Never returned.
      description: JSON Merge Patch request. Omitted fields stay unchanged and explicit null clears nullable fields.
    AsClientList:
      type: object
      required: [clients]
      properties:
        clients:
          type: array
          items:
            $ref: '#/components/schemas/AsClient'
      example:
        clients:
          - clientId: wallet-web
            clientName: Acme web wallet
            clientType: public
            enabled: true
            grantTypes: [authorization_code, refresh_token]
            responseTypes: [code]
            redirectUris: [https://wallet.acme.example/callback]
            tokenEndpointAuthMethod: none
            requirePkce: true
            clientSecretConfigured: false
          - clientId: issuer-backend
            clientName: Issuer backend
            clientType: confidential
            enabled: true
            grantTypes: [client_credentials]
            tokenEndpointAuthMethod: client_secret_basic
            allowedScopes: [issuance]
            clientSecretConfigured: true
    DeleteAsClientResult:
      type: object
      required: [deleted]
      properties:
        deleted:
          type: boolean
          description: True when the client registration existed and was deleted.

    AsIdentifierType:
      type: string
      description: >
        The type of a login identifier. Open, string-valued: extensions may add
        values (for example `vat`, `lei`). Core values are `email`, `phone`,
        `did` (a W3C Decentralized Identifier), and `x509` (an X.509 certificate).
      example: email
    AsAuthMethod:
      type: string
      description: >
        An authentication method the AS login surface accepts for an identity.
        Open, string-valued: extensions may add values.
          - `password`: identifier plus password. The familiar default for first-party applications.
          - `email_otp`: a one-time passcode delivered by email.
          - `magic_link`: a single-use link delivered out of band.
          - `totp`: a time-based one-time password from an authenticator app, used as a second factor.
          - `federated_oidc`: login delegated to an external OIDC identity provider.
          - `wallet`: authentication by verifiable presentation from a wallet.
      example: password
    AsIdentityIdentifier:
      type: object
      description: A login handle for an identity. The `email` identifier is the primary login handle.
      required: [type, value]
      properties:
        type:
          $ref: '#/components/schemas/AsIdentifierType'
        value:
          type: string
          description: The identifier value, such as an email address, phone number, DID, or certificate subject.
          example: sofia.almeida@acme.example
    AsIdentityNaturalPerson:
      type: object
      description: Natural-person details used to create and bind a party to the identity inline.
      properties:
        displayName:
          type: string
          nullable: true
          description: Human-readable label for the natural person.
          example: Sofia Almeida
        electronicAddresses:
          type: array
          nullable: true
          description: Electronic contact points to attach to the created party, such as email addresses.
          items:
            type: object
            required: [addressType, value]
            properties:
              addressType:
                type: string
                description: Kind of electronic contact point, such as `EMAIL` or `PHONE`.
                example: EMAIL
              value:
                type: string
                description: The address value, such as the email address or phone number.
                example: sofia.almeida@acme.example
        firstName:
          type: string
          nullable: true
          description: Given name of the natural person.
          example: Sofia
        lastName:
          type: string
          nullable: true
          description: Family name of the natural person.
          example: Almeida
    AsIdentityPartyBinding:
      type: object
      description: >
        Optional binding of the identity to a party. Provide `existingPartyId`
        to bind an existing party, or `naturalPerson` to create and bind a
        natural person inline. The same seam later carries organization,
        organization-unit, and group bindings.
      oneOf:
        - type: object
          required: [existingPartyId]
          properties:
            existingPartyId:
              type: string
              format: uuid
              description: Identifier of an existing party to bind to the identity.
              example: 9b2c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        - type: object
          required: [naturalPerson]
          properties:
            naturalPerson:
              $ref: '#/components/schemas/AsIdentityNaturalPerson'
    AsIdentityCredential:
      description: >
        Initial credential for the identity. Omit to have the server generate a
        one-time activation code returned once in the create response.
      oneOf:
        - type: object
          required: [password]
          properties:
            password:
              type: string
              writeOnly: true
              minLength: 12
              description: Initial password for the identity. Never returned.
              example: correct-horse-battery-staple
    AsIdentityCreateRequest:
      type: object
      description: >
        Request to provision an authenticating identity with login identifiers,
        an optional credential, and an optional party binding.
      required: [identifiers]
      properties:
        displayName:
          type: string
          nullable: true
          description: Convenience label on the identity.
          example: Sofia Almeida
        identifiers:
          type: array
          minItems: 1
          description: Login handles for the identity. At least one is required; an `email` identifier is the primary login handle.
          items:
            $ref: '#/components/schemas/AsIdentityIdentifier'
        credential:
          $ref: '#/components/schemas/AsIdentityCredential'
        allowedMethods:
          type: array
          nullable: true
          description: Authentication methods the AS login surface accepts for this identity.
          default: [password]
          items:
            $ref: '#/components/schemas/AsAuthMethod'
        partyBinding:
          allOf:
            - $ref: '#/components/schemas/AsIdentityPartyBinding'
          nullable: true
          description: Optional binding of the identity to an existing party or an inline natural person.
      example:
        displayName: Sofia Almeida
        identifiers:
          - type: email
            value: sofia.almeida@acme.example
        credential:
          password: correct-horse-battery-staple
        allowedMethods: [password]
    AsIdentity:
      type: object
      description: An authenticating identity registered against the AS.
      required: [identityId, identifiers, enabled, createdAt]
      properties:
        identityId:
          type: string
          format: uuid
          description: Stable identifier of the identity.
          example: 1d9f5c3a-2b7e-4f81-9c0d-6a8bd7f6d211
        displayName:
          type: string
          nullable: true
          description: Convenience label on the identity.
          example: Sofia Almeida
        identifiers:
          type: array
          description: Login handles registered for the identity.
          items:
            $ref: '#/components/schemas/AsIdentityIdentifier'
        enabled:
          type: boolean
          description: Enables the identity for authentication against the AS.
          example: true
        partyId:
          type: string
          format: uuid
          nullable: true
          description: Identifier of the bound party, or null when the identity is unbound.
          example: 9b2c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        partyType:
          type: string
          nullable: true
          description: Type of the bound party, such as `naturalPerson`, or null when the identity is unbound.
          example: naturalPerson
        createdAt:
          type: string
          format: date-time
          description: When the identity was created.
          example: '2026-01-15T09:30:00Z'
      example:
        identityId: 1d9f5c3a-2b7e-4f81-9c0d-6a8bd7f6d211
        displayName: Sofia Almeida
        identifiers:
          - type: email
            value: sofia.almeida@acme.example
        enabled: true
        partyId: 9b2c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
        partyType: naturalPerson
        createdAt: '2026-01-15T09:30:00Z'
    AsIdentityCreateResult:
      allOf:
        - $ref: '#/components/schemas/AsIdentity'
        - type: object
          properties:
            activationCode:
              type: string
              nullable: true
              description: One-time activation code. Present only when no credential was supplied. Returned once and never re-read.
              example: 4F8K-2Q7M-9X1P
            userCode:
              type: string
              nullable: true
              description: Alias of the one-time activation code. Present only when no credential was supplied.
              example: 4F8K-2Q7M-9X1P
    AsIdentityList:
      type: object
      required: [identities]
      properties:
        identities:
          type: array
          items:
            $ref: '#/components/schemas/AsIdentity'
      example:
        identities:
          - identityId: 1d9f5c3a-2b7e-4f81-9c0d-6a8bd7f6d211
            displayName: Sofia Almeida
            identifiers:
              - type: email
                value: sofia.almeida@acme.example
            enabled: true
            partyId: 9b2c2d9e-1f4a-4c8b-9e2d-5a6f7c8b9d01
            partyType: naturalPerson
            createdAt: '2026-01-15T09:30:00Z'
    DeleteAsIdentityResult:
      type: object
      required: [deleted]
      properties:
        deleted:
          type: boolean
          description: True when the identity existed and was deleted.
    AsIdentityCredentialResetRequest:
      type: object
      description: >
        Operator request to set or reset an identity's login credential. Supply a
        password to set it directly; omit it to have the server generate a new
        one-time activation code returned once in the response. Any existing
        credential is overwritten.
      properties:
        password:
          type: string
          writeOnly: true
          minLength: 12
          description: New password for the identity. Omit to regenerate a one-time activation code instead. Never returned.
          example: correct-horse-battery-staple
    AsIdentityCredentialResetResult:
      type: object
      properties:
        activationCode:
          type: string
          nullable: true
          description: One-time activation code. Present only when no password was supplied. Returned once and never re-read.
          example: 4F8K-2Q7M-9X1P
        userCode:
          type: string
          nullable: true
          description: Alias of the one-time activation code. Present only when no password was supplied.
          example: 4F8K-2Q7M-9X1P
        passwordChangedAt:
          type: string
          format: date-time
          nullable: true
          description: When the credential was updated.
          example: '2026-06-15T09:30:00Z'

    Oid4vciIssuerMetadataSettings:
      type: object
      description: >
        Write shape for the tenant OID4VCI issuer metadata section. These fields
        map to issuer identifier, authorization-server references, display
        metadata, and signed issuer metadata key descriptors.
      properties:
        issuerIdentifier:
          type: string
          format: uri
          nullable: true
          description: Issuer identifier advertised in OID4VCI issuer metadata.
          example: https://issuer.acme.example
        authorizationServers:
          type: array
          nullable: true
          description: Authorization servers accepted by this issuer, by tenant AS id or issuer URL.
          items:
            type: string
          example: [https://auth.acme.example]
        displayName:
          type: string
          nullable: true
          description: Default issuer display name for wallet metadata.
          example: Acme Workforce Issuer
        displayLocale:
          type: string
          nullable: true
          description: BCP 47 locale for the default display entry.
          example: en-US
        signedMetadataEnabled:
          type: boolean
          nullable: true
          description: Enables signed issuer metadata when a signing key alias and KMS provider id are configured.
        metadataSigningKeyAlias:
          type: string
          nullable: true
          description: Alias of the KMS-managed key used to sign issuer metadata.
          example: oid4vci-metadata-signing
        metadataSigningKmsProviderId:
          type: string
          nullable: true
          description: KMS provider id that owns `metadataSigningKeyAlias`.
          example: software-kms
      example:
        issuerIdentifier: https://issuer.acme.example
        authorizationServers: [https://auth.acme.example]
        displayName: Acme Workforce Issuer
        displayLocale: en-US
        signedMetadataEnabled: true
        metadataSigningKeyAlias: oid4vci-metadata-signing
        metadataSigningKmsProviderId: software-kms
    Oid4vciIssuerMetadataSettingsView:
      type: object
      description: Effective OID4VCI issuer metadata settings with source markers.
      properties:
        issuerIdentifier:
          $ref: '#/components/schemas/StringConfigField'
        authorizationServers:
          $ref: '#/components/schemas/StringListConfigField'
        displayName:
          $ref: '#/components/schemas/StringConfigField'
        displayLocale:
          $ref: '#/components/schemas/StringConfigField'
        signedMetadataEnabled:
          $ref: '#/components/schemas/BooleanConfigField'
        metadataSigningKeyAlias:
          $ref: '#/components/schemas/StringConfigField'
        metadataSigningKmsProviderId:
          $ref: '#/components/schemas/StringConfigField'
      example:
        issuerIdentifier: { value: https://issuer.acme.example, source: tenant }
        authorizationServers: { value: [https://auth.acme.example], source: tenant }
        displayName: { value: Acme Workforce Issuer, source: tenant }
        displayLocale: { value: en-US, source: tenant }
        signedMetadataEnabled: { value: true, source: tenant }
        metadataSigningKeyAlias: { value: oid4vci-metadata-signing, source: tenant }
        metadataSigningKmsProviderId: { value: software-kms, source: tenant }
    Oid4vciIssuerSecuritySettings:
      type: object
      description: >
        Write shape for OID4VCI credential response and request encryption
        metadata. Key aliases are descriptors only; private key material remains
        in the configured KMS/secrets backend.
      properties:
        credentialResponseEncryptionAlgValuesSupported:
          type: array
          nullable: true
          description: JWE algorithms the issuer advertises for encrypted credential responses.
          items:
            type: string
          example: [ECDH-ES, RSA-OAEP-256]
        credentialResponseEncryptionEncValuesSupported:
          type: array
          nullable: true
          description: JWE content-encryption algorithms the issuer advertises for encrypted credential responses.
          items:
            type: string
          example: [A256GCM]
        credentialResponseEncryptionZipValuesSupported:
          type: array
          nullable: true
          description: Compression algorithms the issuer advertises for encrypted credential responses.
          items:
            type: string
          example: [DEF]
        credentialResponseEncryptionRequired:
          type: boolean
          nullable: true
          description: Requires wallets to encrypt credential responses when supported by the selected issuance flow.
        credentialRequestDecryptionKeyAlias:
          type: string
          nullable: true
          description: Alias of the KMS-managed ECDH key used to decrypt encrypted credential requests.
          example: oid4vci-request-decryption
        credentialRequestDecryptionKmsProviderId:
          type: string
          nullable: true
          description: KMS provider id that owns `credentialRequestDecryptionKeyAlias`.
          example: software-kms
        credentialRequestEncryptionEncValuesSupported:
          type: array
          nullable: true
          description: JWE content-encryption algorithms accepted for encrypted credential requests.
          items:
            type: string
          example: [A256GCM]
        credentialRequestEncryptionZipValuesSupported:
          type: array
          nullable: true
          description: Compression algorithms accepted for encrypted credential requests.
          items:
            type: string
          example: [DEF]
        credentialRequestEncryptionRequired:
          type: boolean
          nullable: true
          description: Requires wallets to encrypt credential requests before submission.
      example:
        credentialResponseEncryptionAlgValuesSupported: [ECDH-ES]
        credentialResponseEncryptionEncValuesSupported: [A256GCM]
        credentialResponseEncryptionRequired: true
        credentialRequestDecryptionKeyAlias: oid4vci-request-decryption
        credentialRequestDecryptionKmsProviderId: software-kms
        credentialRequestEncryptionEncValuesSupported: [A256GCM]
        credentialRequestEncryptionRequired: false
    Oid4vciIssuerSecuritySettingsView:
      type: object
      description: Effective OID4VCI issuer security settings with source markers.
      properties:
        credentialResponseEncryptionAlgValuesSupported:
          $ref: '#/components/schemas/StringListConfigField'
        credentialResponseEncryptionEncValuesSupported:
          $ref: '#/components/schemas/StringListConfigField'
        credentialResponseEncryptionZipValuesSupported:
          $ref: '#/components/schemas/StringListConfigField'
        credentialResponseEncryptionRequired:
          $ref: '#/components/schemas/BooleanConfigField'
        credentialRequestDecryptionKeyAlias:
          $ref: '#/components/schemas/StringConfigField'
        credentialRequestDecryptionKmsProviderId:
          $ref: '#/components/schemas/StringConfigField'
        credentialRequestEncryptionEncValuesSupported:
          $ref: '#/components/schemas/StringListConfigField'
        credentialRequestEncryptionZipValuesSupported:
          $ref: '#/components/schemas/StringListConfigField'
        credentialRequestEncryptionRequired:
          $ref: '#/components/schemas/BooleanConfigField'
      example:
        credentialResponseEncryptionAlgValuesSupported: { value: [ECDH-ES], source: tenant }
        credentialResponseEncryptionEncValuesSupported: { value: [A256GCM], source: tenant }
        credentialResponseEncryptionZipValuesSupported: { value: [DEF], source: default }
        credentialResponseEncryptionRequired: { value: true, source: tenant }
        credentialRequestDecryptionKeyAlias: { value: oid4vci-request-decryption, source: tenant }
        credentialRequestDecryptionKmsProviderId: { value: software-kms, source: tenant }
        credentialRequestEncryptionEncValuesSupported: { value: [A256GCM], source: tenant }
        credentialRequestEncryptionZipValuesSupported: { value: [DEF], source: default }
        credentialRequestEncryptionRequired: { value: false, source: tenant }
    Oid4vciIssuerIssuanceSettings:
      type: object
      description: Issuance tuning that belongs to the issuer runtime, not to credential designs.
      properties:
        batchCredentialIssuanceMaxSize:
          type: integer
          minimum: 1
          nullable: true
          description: Maximum number of credentials the issuer accepts in a batch credential request.
          example: 10
        issuanceClockSkewInSeconds:
          type: integer
          minimum: 0
          nullable: true
          description: Clock skew accepted when validating issuance-time artifacts.
          example: 60
      example:
        batchCredentialIssuanceMaxSize: 10
        issuanceClockSkewInSeconds: 60
    Oid4vciIssuerIssuanceSettingsView:
      type: object
      description: Effective OID4VCI issuer issuance settings with source markers.
      properties:
        batchCredentialIssuanceMaxSize:
          $ref: '#/components/schemas/IntegerConfigField'
        issuanceClockSkewInSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
      example:
        batchCredentialIssuanceMaxSize: { value: 10, source: tenant }
        issuanceClockSkewInSeconds: { value: 60, source: default }

    Oid4vpVerifierClientSettings:
      type: object
      description: OID4VP verifier client identity and redirect settings used as defaults for authorization requests.
      properties:
        externalBaseUrl:
          type: string
          format: uri
          nullable: true
          description: Public base URL used to construct verifier-facing endpoints.
          example: https://verify.acme.example
        responseUri:
          type: string
          format: uri
          nullable: true
          description: Direct-post response URI advertised for wallet authorization responses.
          example: https://verify.acme.example/direct_post
        authBridgeClientId:
          type: string
          nullable: true
          description: OAuth2 client id used when the verifier delegates through the authorization bridge.
          example: acme-workforce-verifier
        authBridgeResponseUri:
          type: string
          format: uri
          nullable: true
          description: Redirect URI used by the authorization bridge client.
          example: https://verify.acme.example/auth/callback
      example:
        externalBaseUrl: https://verify.acme.example
        responseUri: https://verify.acme.example/direct_post
        authBridgeClientId: acme-workforce-verifier
        authBridgeResponseUri: https://verify.acme.example/auth/callback
    Oid4vpVerifierClientSettingsView:
      type: object
      description: Effective OID4VP verifier client settings with source markers.
      properties:
        externalBaseUrl:
          $ref: '#/components/schemas/StringConfigField'
        responseUri:
          $ref: '#/components/schemas/StringConfigField'
        authBridgeClientId:
          $ref: '#/components/schemas/StringConfigField'
        authBridgeResponseUri:
          $ref: '#/components/schemas/StringConfigField'
      example:
        externalBaseUrl: { value: https://verify.acme.example, source: tenant }
        responseUri: { value: https://verify.acme.example/direct_post, source: tenant }
        authBridgeClientId: { value: acme-workforce-verifier, source: tenant }
        authBridgeResponseUri: { value: https://verify.acme.example/auth/callback, source: tenant }
    Oid4vpVerifierRequestObjectSigningSettings:
      type: object
      description: >
        Request-object signing defaults for the verifier. Key fields are KMS
        descriptors; private key material is not stored in platform config.
      properties:
        enabled:
          type: boolean
          nullable: true
          description: Enables signed authorization request objects.
        mode:
          type: string
          nullable: true
          description: Signing binding mode, for example `did:jwk`, `did:web`, or `x5c`.
          example: did:web
        keyAlias:
          type: string
          nullable: true
          description: Alias of the KMS-managed signing key used for request objects.
          example: oid4vp-request-object-signing
        providerId:
          type: string
          nullable: true
          description: KMS provider id that owns `keyAlias`.
          example: software-kms
        includeIss:
          type: boolean
          nullable: true
          description: Includes an `iss` claim in signed request objects.
        audience:
          type: string
          nullable: true
          description: Audience value placed in signed request objects.
          example: https://wallet-provider.example
        expirationSeconds:
          type: integer
          minimum: 1
          nullable: true
          description: Lifetime of a signed request object in seconds.
          example: 300
        didWebDomain:
          type: string
          nullable: true
          description: did:web domain used when `mode` is `did:web`.
          example: verify.acme.example
        sanDnsName:
          type: string
          nullable: true
          description: DNS subject alternative name used for certificate-bound signing modes.
          example: verify.acme.example
        verificationMethodId:
          type: string
          nullable: true
          description: Fully qualified verification method id advertised for request-object signatures.
          example: did:web:verify.acme.example#request-object
        verificationMethodFragment:
          type: string
          nullable: true
          description: Verification method fragment used to build the method id when applicable.
          example: request-object
      example:
        enabled: true
        mode: did:web
        keyAlias: oid4vp-request-object-signing
        providerId: software-kms
        includeIss: true
        audience: https://wallet-provider.example
        expirationSeconds: 300
        didWebDomain: verify.acme.example
        verificationMethodFragment: request-object
    Oid4vpVerifierRequestObjectSigningSettingsView:
      type: object
      description: Effective OID4VP verifier request-object signing settings with source markers.
      properties:
        enabled:
          $ref: '#/components/schemas/BooleanConfigField'
        mode:
          $ref: '#/components/schemas/StringConfigField'
        keyAlias:
          $ref: '#/components/schemas/StringConfigField'
        providerId:
          $ref: '#/components/schemas/StringConfigField'
        includeIss:
          $ref: '#/components/schemas/BooleanConfigField'
        audience:
          $ref: '#/components/schemas/StringConfigField'
        expirationSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
        didWebDomain:
          $ref: '#/components/schemas/StringConfigField'
        sanDnsName:
          $ref: '#/components/schemas/StringConfigField'
        verificationMethodId:
          $ref: '#/components/schemas/StringConfigField'
        verificationMethodFragment:
          $ref: '#/components/schemas/StringConfigField'
      example:
        enabled: { value: true, source: tenant }
        mode: { value: did:web, source: tenant }
        keyAlias: { value: oid4vp-request-object-signing, source: tenant }
        providerId: { value: software-kms, source: tenant }
        includeIss: { value: true, source: tenant }
        audience: { value: https://wallet-provider.example, source: tenant }
        expirationSeconds: { value: 300, source: default }
        didWebDomain: { value: verify.acme.example, source: tenant }
        verificationMethodFragment: { value: request-object, source: tenant }
    Oid4vpVerifierSessionSettings:
      type: object
      description: Authorization-session lifetime settings for the verifier runtime.
      properties:
        sessionTtlSeconds:
          type: integer
          minimum: 1
          nullable: true
          description: Authorization-session time to live in seconds.
          example: 300
      example:
        sessionTtlSeconds: 300
    Oid4vpVerifierSessionSettingsView:
      type: object
      description: Effective OID4VP verifier session settings with source markers.
      properties:
        sessionTtlSeconds:
          $ref: '#/components/schemas/IntegerConfigField'
      example:
        sessionTtlSeconds: { value: 300, source: default }
    Oid4vpVerifierReconciliationSettings:
      type: object
      description: >
        Identity reconciliation behavior after a presentation response. DCQL
        queries and reconciliation policies stay in their own stores; this
        section only controls verifier runtime defaults.
      properties:
        autoCreateUser:
          type: boolean
          nullable: true
          description: Creates a local user record when reconciliation does not find one.
        requireReconciliation:
          type: boolean
          nullable: true
          description: Requires verifier responses to resolve to a user before completion.
        userIdentifierClaimPath:
          type: string
          nullable: true
          description: Claim path used as the user reconciliation key.
          example: sub
        frontendUrl:
          type: string
          format: uri
          nullable: true
          description: Frontend URL used for reconciliation or user interaction.
          example: https://app.acme.example/verify
        stsBaseUrl:
          type: string
          format: uri
          nullable: true
          description: Security token service base URL used by reconciliation integrations.
          example: https://sts.acme.example
      example:
        autoCreateUser: false
        requireReconciliation: true
        userIdentifierClaimPath: sub
        frontendUrl: https://app.acme.example/verify
        stsBaseUrl: https://sts.acme.example
    Oid4vpVerifierReconciliationSettingsView:
      type: object
      description: Effective OID4VP verifier reconciliation settings with source markers.
      properties:
        autoCreateUser:
          $ref: '#/components/schemas/BooleanConfigField'
        requireReconciliation:
          $ref: '#/components/schemas/BooleanConfigField'
        userIdentifierClaimPath:
          $ref: '#/components/schemas/StringConfigField'
        frontendUrl:
          $ref: '#/components/schemas/StringConfigField'
        stsBaseUrl:
          $ref: '#/components/schemas/StringConfigField'
      example:
        autoCreateUser: { value: false, source: default }
        requireReconciliation: { value: true, source: tenant }
        userIdentifierClaimPath: { value: sub, source: default }
        frontendUrl: { value: https://app.acme.example/verify, source: tenant }
        stsBaseUrl: { value: https://sts.acme.example, source: tenant }

    CreateOid4vciIssuerInstanceRequest:
      type: object
      description: >
        Create request for an OID4VCI issuer instance. The command creates a VDX
        software party with an OID4VCI_ISSUER capability, projects a tenant public
        endpoint, and stores config rows under `oid4vci.issuers.<instanceId>.*`.
      required: [displayName, managementMode]
      properties:
        displayName:
          type: string
          description: Human-readable issuer instance name.
          example: Acme Workforce Issuer
        managementMode:
          $ref: './software-manager-components.yml#/components/schemas/ManagementMode'
        runtimeMode:
          $ref: './software-manager-components.yml#/components/schemas/RuntimeMode'
        authorizationServerId:
          type: string
          format: uuid
          nullable: true
          description: Optional AS software party id this issuer uses.
          example: 996d5f68-8836-4af1-b6da-1330b42a2805
        discoveryUrl:
          type: string
          format: uri
          nullable: true
          description: Optional external issuer discovery URL for EXTERNAL or HYBRID instances.
          example: https://issuer.acme.example/.well-known/openid-credential-issuer
        config:
          $ref: './software-manager-components.yml#/components/schemas/Oid4vciIssuerConfig'
        host:
          type: string
          nullable: true
          description: Optional custom host, lower-case and without scheme or port, for the issuer public surface.
          example: issuer.acme.example
        pathPrefix:
          type: string
          nullable: true
          description: Optional route prefix. When absent the service derives one from the tenant and instance id.
          example: /oid4vci
    UpdateOid4vciIssuerInstanceRequest:
      type: object
      description: Partial update request for OID4VCI issuer instance metadata and initial runtime config fields.
      properties:
        displayName:
          type: string
          description: Replacement issuer display name.
        config:
          $ref: './software-manager-components.yml#/components/schemas/Oid4vciIssuerConfig'
    Oid4vciIssuerInstance:
      $ref: './software-manager-components.yml#/components/schemas/Oid4vciIssuerDetail'
    Oid4vciIssuerInstanceList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Oid4vciIssuerInstance'
        page:
          $ref: '#/components/schemas/PlatformConfigPageMeta'

    CreateOid4vpVerifierInstanceRequest:
      type: object
      description: >
        Create request for an OID4VP verifier instance. The command creates a VDX
        software party with an OID4VP_VERIFIER capability, projects a tenant public
        endpoint, and stores config rows under `oid4vp.verifiers.<instanceId>.*`.
      required: [displayName, managementMode]
      properties:
        displayName:
          type: string
          description: Human-readable verifier instance name.
          example: Acme Workforce Verifier
        managementMode:
          $ref: './software-manager-components.yml#/components/schemas/ManagementMode'
        runtimeMode:
          $ref: './software-manager-components.yml#/components/schemas/RuntimeMode'
        authorizationServerId:
          type: string
          format: uuid
          nullable: true
          description: Optional AS software party id this verifier uses.
          example: 996d5f68-8836-4af1-b6da-1330b42a2805
        discoveryUrl:
          type: string
          format: uri
          nullable: true
          description: Optional verifier discovery URL for EXTERNAL or HYBRID instances.
          example: https://verify.acme.example/.well-known/oauth-authorization-server
        config:
          $ref: './software-manager-components.yml#/components/schemas/Oid4vpVerifierConfig'
        host:
          type: string
          nullable: true
          description: Optional custom host, lower-case and without scheme or port, for the verifier public surface.
          example: verify.acme.example
        pathPrefix:
          type: string
          nullable: true
          description: Optional route prefix. When absent the service derives one from the tenant and instance id.
          example: /oid4vp
    UpdateOid4vpVerifierInstanceRequest:
      type: object
      description: Partial update request for OID4VP verifier instance metadata and initial runtime config fields.
      properties:
        displayName:
          type: string
          description: Replacement verifier display name.
        config:
          $ref: './software-manager-components.yml#/components/schemas/Oid4vpVerifierConfig'
    Oid4vpVerifierInstance:
      $ref: './software-manager-components.yml#/components/schemas/Oid4vpVerifierDetail'
    Oid4vpVerifierInstanceList:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Oid4vpVerifierInstance'
        page:
          $ref: '#/components/schemas/PlatformConfigPageMeta'

    PlatformConfigPageMeta:
      type: object
      description: Page metadata returned by list operations.
      properties:
        page:
          type: integer
          minimum: 0
          example: 0
        size:
          type: integer
          minimum: 1
          example: 20
        totalElements:
          type: integer
          minimum: 0
          example: 1
        totalPages:
          type: integer
          minimum: 0
          example: 1

    ConfigBackendDescriptor:
      type: object
      description: Registered configuration backend descriptor.
      required: [backendId, type, partitionStrategy]
      properties:
        backendId:
          type: string
          example: database
        type:
          type: string
          enum: [DATABASE, AZURE_APP_CONFIGURATION]
        enabled:
          type: boolean
          default: true
        partitionStrategy:
          type: string
          description: How tenant and instance addresses map onto native backend keys.
          enum: [TENANT_COLUMN_INSTANCE_PREFIX, TENANT_LABEL_INSTANCE_PREFIX, DEDICATED_BACKEND]
        settings:
          type: object
          additionalProperties: true
          description: Type-specific non-secret connection settings.
    SecretsBackendDescriptor:
      type: object
      description: Registered secrets backend. Credentials are represented by secret references, not plaintext.
      required: [backendId, type, partitionStrategy]
      properties:
        backendId:
          type: string
          example: tenant-vault
        type:
          type: string
          enum: [KMS, VAULT, AZURE_KEY_VAULT, AWS_SECRETS_MANAGER, KUBERNETES_SECRET_MOUNT]
        enabled:
          type: boolean
          default: true
        partitionStrategy:
          type: string
          enum: [TENANT_PATH_INSTANCE_PATH, TENANT_LABEL_INSTANCE_PREFIX, DEDICATED_BACKEND]
        credentialRef:
          $ref: '#/components/schemas/SecretReference'
        settings:
          type: object
          additionalProperties: true
    BackendDefaults:
      type: object
      description: Platform-wide default backend binding.
      properties:
        defaultConfigBackendId:
          type: string
          example: database
        defaultSecretsBackendId:
          type: string
          example: tenant-vault