kms-openapi.yml

openapi: 3.0.4
info:
  title: KMS REST Server API
  version: 0.1.0
  description: |
    The Key Management System (KMS) REST API lets an application manage cryptographic keys
    and perform raw signing operations without handling private key material directly. A key
    provider is a configured backend that holds and operates on keys: a software (in-memory
    or persisted) provider, AWS KMS, or Azure Key Vault. The API lets you inspect the
    configured key providers; generate keys, register existing provider keys, import
    externally supplied keys, and list or look up keys by alias or kid (key id); resolve a
    public key (for example from a JWK, kid, X.509 chain, or DID) through a key resolver
    service; and create and verify raw detached signatures over arbitrary bytes using a
    managed key.

    Keys are addressed either by a chosen `alias` (for example `my-signing-key`) or by their
    generated `kid` (for example `00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE`). Every key
    belongs to exactly one provider, identified by a `providerId` such as `testsoftware`.
    Signing input and signature bytes are carried as base64-encoded strings on the wire.

    Every request must carry a JWT bearer token in the `Authorization` header
    (`Authorization: Bearer <token>`). The token is the sole authentication and
    tenant-resolution mechanism. The optional `X-Tenant-ID` and `X-User-ID` headers are
    impersonation hints only and are never used as an authentication fallback; they are
    ignored unless the caller is already authorized to act on behalf of that tenant or user.
    Keys are isolated per tenant, so a key generated for one tenant is never visible to
    another.
  contact:
    name: Sphereon International B.V.
    email: support@sphereon.com
    url: 'https://sphereon.com'
servers:
  - url: http://localhost:8080/api/kms/v1
    description: Development server
tags:
  - name: Providers
    description: >
      Inspect configured key providers and manage the keys held by a specific provider
      (list, generate, import, get, delete under /providers/{providerId}).
  - name: KMS
    description: >
      Provider-agnostic key operations across all of the tenant's providers
      (list, generate, import, register, get, delete under /keys).
  - name: Resolvers
    description: >
      Inspect key resolver services and resolve a public key from a reference such as a
      JWK, kid, X.509 chain, or DID.
  - name: Signatures
    description: Create and verify raw (detached) cryptographic signatures using a managed key.
  - name: Capabilities
    description: Inspect provider capabilities and select providers by capability criteria.
  - name: Encryption
    description: Encrypt, decrypt, wrap, unwrap, and perform key agreement using managed keys.
  - name: Certificates
    description: Generate CSRs, issue X.509 certificates, and manage certificate stores.
security:
  - bearer: [ ]
paths:
  /providers:
    get:
      tags: [ Providers ]
      summary: List configured key providers
      description: >
        Returns every key provider that is configured and available for the calling
        tenant. Providers are configured server-side (for example a `SOFTWARE`,
        `AWS_KMS`, or `AZURE_KEYVAULT` provider); this endpoint does not create them.
        Use the returned `providerId` (for example `testsoftware`) to scope key
        operations to a specific provider.
      operationId: listKeyProviders
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: A list of Key Provider configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListKeyProvidersResponse'
              example:
                providers:
                  - providerId: "testsoftware"
                    type: "SOFTWARE"
        '500':
          $ref: '#/components/responses/InternalServerError'
#    post:
#      tags: [ Providers ]
#      summary: Create a new Key Provider
#      operationId: createKeyProvider
#      requestBody:
#        $ref: '#/components/requestBodies/CreateKeyProviderRequest'
#      responses:
#        '201':
#          description: Key Provider created successfully.
#          content:
#            application/json:
#              schema:
#                $ref: '#/components/schemas/KeyProviderResponse'
#        '400':
#          $ref: '#/components/responses/BadRequest'
#        '500':
#          $ref: '#/components/responses/InternalServerError'

  /providers/{providerId}:
    parameters:
      - $ref: '#/components/parameters/ProviderId'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Providers ]
      summary: Get key provider details
      description: >
        Returns the configuration details of a single key provider identified by its
        `providerId` path parameter (for example `testsoftware`). Returns 404 if no
        provider with that id is configured for the calling tenant.
      operationId: getKeyProvider
      responses:
        '200':
          description: Key Provider details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyProviderResponse'
              example:
                providerId: "testsoftware"
                type: "SOFTWARE"
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
#    put:
#      tags: [ Providers ]
#      summary: Update Key Provider configuration
#      operationId: updateKeyProvider
#      requestBody:
#        $ref: '#/components/requestBodies/UpdateKeyProviderRequest'
#      responses:
#        '200':
#          description: Key Provider updated successfully.
#          content:
#            application/json:
#              schema:
#                $ref: '#/components/schemas/KeyProviderResponse'
#        '400':
#          $ref: '#/components/responses/BadRequest'
#        '404':
#          $ref: '#/components/responses/NotFound'
#        '500':
#          $ref: '#/components/responses/InternalServerError'
#    delete:
#      tags: [ Providers ]
#      summary: Delete Key Provider
#      operationId: deleteKeyProvider
#      responses:
#        '204':
#          description: Key Provider deleted successfully.
#        '404':
#          $ref: '#/components/responses/NotFound'
#        '500':
#          $ref: '#/components/responses/InternalServerError'

  /providers/{providerId}/keys:
    parameters:
      - $ref: '#/components/parameters/ProviderId'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Providers ]
      summary: List all managed cryptographic keys for a provider
      description: >
        Lists the keys managed by the provider identified by `providerId`. Only key
        metadata is returned (alias, kid, algorithm, type); private key material is
        never included. Returns 404 if the provider id is unknown for the calling
        tenant. Results are scoped to the calling tenant only.
      operationId: providerListKeys
      responses:
        '200':
          description: A list of all managed keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListKeysResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [ Providers ]
      summary: Generate a new key in a provider
      description: >
        Generates a new key inside the provider identified by `providerId`. The
        request body selects the signature algorithm (for example `ECDSA_SHA256`), and
        optionally an `alias`, intended `use` (`sig`/`enc`), and `keyOperations`. If no
        alias is given the provider assigns one. The response contains the generated key
        pair including its `kid`, `alias`, and the public JWK. Returns 404 if the
        provider id is unknown, or 400 if the requested algorithm is not supported.
      operationId: providerGenerateKey
      requestBody:
        $ref: '#/components/requestBodies/GenerateKeyRequest'
      responses:
        '201':
          description: Key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateKeyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /providers/{providerId}/keys/import:
    parameters:
      - $ref: '#/components/parameters/ProviderId'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    post:
      tags: [ Providers ]
      summary: Import externally supplied key material into a provider
      description: >
        Imports a key that you already hold (its key material is supplied in the request
        body as a JWK) into the provider identified by `providerId`. The body must carry
        a fully resolved `keyInfo` (the `key` JWK is required). Returns 404 if the
        provider id is unknown, or 400 if the supplied keyInfo is invalid.
      operationId: providerImportKey
      requestBody:
        $ref: '#/components/requestBodies/ImportKeyRequest'
      responses:
        '201':
          description: Key imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportKeyResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /providers/{providerId}/keys/{aliasOrKid}:
    parameters:
      - $ref: '#/components/parameters/ProviderId'
      - $ref: '#/components/parameters/AliasOrKid'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Providers ]
      summary: Get a specific managed key by alias or kid
      description: >
        Looks up a single key in the provider identified by `providerId`. The
        `aliasOrKid` path parameter may be either the key's alias (for example
        `my-signing-key`) or its kid (for example
        `00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE`). Returns 404 if the provider id
        is unknown or no key matches the alias or kid in that provider.
      operationId: providerGetKey
      responses:
        '200':
          description: The managed key for the specified provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKeyResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    #    put:
    #      tags: [ Providers ]
    #      summary: Update a stored key (reserved for future use)
    #      operationId: updateKey
    #      requestBody:
    #        $ref: '#/components/requestBodies/UpdateKeyRequest'
    #      responses:
    #        '200':
    #          description: Key updated successfully
    #          content:
    #            application/json:
    #              schema:
    #                $ref: '#/components/schemas/ManagedKeyInfo'
    #        '400':
    #          $ref: '#/components/responses/BadRequest'
    #        '404':
    #          $ref: '#/components/responses/NotFound'
    #        '500':
    #          $ref: '#/components/responses/InternalServerError'
    delete:
      tags: [ Providers ]
      summary: Delete a key from a provider
      description: >
        Permanently removes the key identified by `aliasOrKid` from the provider
        identified by `providerId`. The `aliasOrKid` may be the key's alias or its kid.
        Returns 204 with no body on success, or 404 if the provider id is unknown or no
        matching key exists.
      operationId: providerDeleteKey
      responses:
        '204':
          description: Key deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

#  /providers/{providerId}/signatures/simple:
#    parameters:
#      - $ref: '#/components/parameters/ProviderId'
#    post:
#      tags: [ Signatures ]
#      summary: Create a digital signature
#      operationId: createSimpleSignature
#      requestBody:
#        $ref: '#/components/requestBodies/CreateSimpleSignatureRequest'
#      responses:
#        '201':
#          description: Signature created successfully
#          content:
#            application/json:
#              schema:
#                $ref: '#/components/schemas/SignOutput'
#        '400':
#          $ref: '#/components/responses/BadRequest'
#        '404':
#          $ref: '#/components/responses/NotFound'
#        '500':
#          $ref: '#/components/responses/InternalServerError'
#
#  /providers/{providerId}/signatures/simple/verify:
#    parameters:
#      - $ref: '#/components/parameters/ProviderId'
#    post:
#      tags: [ Signatures ]
#      summary: Verify a digital signature
#      operationId: isValidSimpleSignature
#      requestBody:
#        $ref: '#/components/requestBodies/VerifySimpleSignatureRequest'
#      responses:
#        '200':
#          description: Signature verification performed successfully
#          content:
#            application/json:
#              schema:
#                $ref: '#/components/schemas/SignatureVerificationResponse'
#        '400':
#          $ref: '#/components/responses/BadRequest'
#        '500':
#          $ref: '#/components/responses/InternalServerError'

  /capabilities:
    get:
      tags: [ Capabilities ]
      summary: List provider capabilities
      description: >
        Returns the capability report for every configured provider. Disabled providers
        are excluded by default.
      operationId: listCapabilities
      parameters:
        - name: includeDisabled
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include disabled providers in the capability report.
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Capabilities for configured providers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCapabilitiesResponse'
              example:
                providers:
                  - providerId: "testsoftware"
                    capabilities:
                      providerId: "testsoftware"
                      providerType: "software"
                      storageTypes: [ "PERSISTENT", "EPHEMERAL" ]
                      supportsKeyImport: true
                      supportsKeyExport: true
                      exposePrivateKeys: false
                      operations:
                        - operation: "GENERATE_KEY"
                          supported: true
                          signatureAlgorithms: [ "ECDSA_SHA256", "ED25519" ]
                        - operation: "ENCRYPT"
                          supported: true
                          contentEncryptionAlgorithms: [ "A128GCM", "A256GCM" ]
                        - operation: "WRAP_KEY"
                          supported: true
                          keyWrapAlgorithms: [ "A128KW", "A256KW" ]
                      supportedKeyTypes: [ "EC", "OKP", "RSA", "OCT" ]
                      supportedCurves: [ "P-256", "P-384", "Ed25519", "X25519" ]
                      supportedCryptoAlgorithms: [ "ECDSA", "ED25519", "X25519", "RSA" ]
                      supportedDigestAlgorithms: [ "SHA256", "SHA384", "SHA512" ]
                      signatureAlgorithms: [ "ECDSA_SHA256", "ED25519", "RSA_SHA256" ]
                      contentEncryptionAlgorithms: [ "A128GCM", "A256GCM" ]
                      supportsX509: true
                      supportsAttestation: false
                      supportsHardwareBacking: false
                      supportsPublicKeyResolution: true
                      resolutionMethods: [ "kid", "key_alias", "jwk" ]
        '500':
          $ref: '#/components/responses/InternalServerError'

  /providers/{providerId}/capabilities:
    parameters:
      - $ref: '#/components/parameters/ProviderId'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Capabilities ]
      summary: Get capabilities for one provider
      operationId: getProviderCapabilities
      responses:
        '200':
          description: Capabilities for the requested provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderCapabilitiesResponse'
              example:
                providerId: "testsoftware"
                capabilities:
                  providerId: "testsoftware"
                  providerType: "software"
                  storageTypes: [ "PERSISTENT" ]
                  supportsKeyImport: true
                  supportsKeyExport: true
                  exposePrivateKeys: false
                  operations:
                    - operation: "SIGN"
                      supported: true
                      signatureAlgorithms: [ "ECDSA_SHA256", "ED25519" ]
                    - operation: "ENCRYPT"
                      supported: true
                      contentEncryptionAlgorithms: [ "A256GCM" ]
                  supportedKeyTypes: [ "EC", "OKP", "OCT" ]
                  supportedCurves: [ "P-256", "Ed25519", "X25519" ]
                  supportedCryptoAlgorithms: [ "ECDSA", "ED25519", "X25519" ]
                  supportedDigestAlgorithms: [ "SHA256", "SHA512" ]
                  signatureAlgorithms: [ "ECDSA_SHA256", "ED25519" ]
                  contentEncryptionAlgorithms: [ "A256GCM" ]
                  supportsX509: true
                  supportsAttestation: false
                  supportsHardwareBacking: false
                  supportsPublicKeyResolution: true
                  resolutionMethods: [ "kid", "key_alias", "jwk" ]
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /providers/query:
    post:
      tags: [ Capabilities ]
      summary: Query matching providers
      description: Returns all providers matching the supplied capability criteria.
      operationId: queryProviders
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/ProviderQueryRequest'
      responses:
        '200':
          description: Matching providers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryProvidersResponse'
              example:
                matches:
                  - providerId: "testsoftware"
                    matchScore: 100
                    capabilities:
                      providerId: "testsoftware"
                      providerType: "software"
                      storageTypes: [ "PERSISTENT" ]
                      supportsKeyImport: true
                      supportsKeyExport: true
                      exposePrivateKeys: false
                      operations:
                        - operation: "ENCRYPT"
                          supported: true
                          contentEncryptionAlgorithms: [ "A256GCM" ]
                      supportedKeyTypes: [ "OCT" ]
                      supportedCurves: [ ]
                      supportedCryptoAlgorithms: [ "HMAC" ]
                      supportedDigestAlgorithms: [ "SHA256" ]
                      signatureAlgorithms: [ "HMAC_SHA256" ]
                      contentEncryptionAlgorithms: [ "A256GCM" ]
                      supportsX509: true
                      supportsAttestation: false
                      supportsHardwareBacking: false
                      supportsPublicKeyResolution: true
                      resolutionMethods: [ "kid", "key_alias" ]
                totalProviders: 2
                matchCount: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /providers/query/best:
    post:
      tags: [ Capabilities ]
      summary: Query the best matching provider
      description: Returns the best provider matching the supplied capability criteria.
      operationId: queryBestProvider
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/ProviderQueryRequest'
      responses:
        '200':
          description: Best matching provider, or null if no provider matches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryBestProviderResponse'
              example:
                match:
                  providerId: "testsoftware"
                  matchScore: 100
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /encryption/encrypt:
    post:
      tags: [ Encryption ]
      summary: Encrypt data
      operationId: encrypt
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/EncryptRequest'
      responses:
        '200':
          description: Encrypted data and AEAD parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EncryptResponse'
              example:
                ciphertext: "8rj9iBf2Vv5uQmE="
                iv: "QkM0hQDUzC7Vqvut"
                authTag: "t6YF2+0M0vO7vKq9Qh7uQg=="
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /encryption/decrypt:
    post:
      tags: [ Encryption ]
      summary: Decrypt data
      operationId: decrypt
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/DecryptRequest'
      responses:
        '200':
          description: Decrypted plaintext.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DecryptResponse'
              example:
                plaintext: "aGVsbG8="
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /encryption/wrap:
    post:
      tags: [ Encryption ]
      summary: Wrap a key
      operationId: wrapKey
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/WrapKeyRequest'
      responses:
        '200':
          description: Wrapped key material.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WrapKeyResponse'
              example:
                wrappedKey: "q83vEj6GTdS3BzN9vdS6F4x1j9p5vQ=="
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /encryption/unwrap:
    post:
      tags: [ Encryption ]
      summary: Unwrap a key
      operationId: unwrapKey
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/UnwrapKeyRequest'
      responses:
        '200':
          description: Unwrapped key material.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnwrapKeyResponse'
              example:
                unwrappedKey: "MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE="
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /encryption/key-agreement:
    post:
      tags: [ Encryption ]
      summary: Perform key agreement
      operationId: performKeyAgreement
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/KeyAgreementRequest'
      responses:
        '200':
          description: Derived shared secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyAgreementResponse'
              example:
                sharedSecret: "oN1hJdAhtf3SW+pm1da4DyxLSFhP0YE6FnW9EeYk7rk="
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificates/csr:
    post:
      tags: [ Certificates ]
      summary: Generate a certificate signing request
      operationId: generateCertificateSigningRequest
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/GenerateCertificateSigningRequestRequest'
      responses:
        '200':
          description: Certificate signing request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateSigningRequestResponse'
              example:
                der: "MIIBKDCBzwIBADCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7oAAwCgYIKoZIzj0EAwIDSAAwRQIhAMiJjZ9Z5w8L7V2qO5n3YgO4Q3t4V6qIh3e3c4C5l7vDAiBd9c0r2k1mWm7y6iY9fKq8pC4d2x3v5z6a7b8c9d0e1g=="
                commonName: "adapter-test.example.com"
                organization: "Sphereon"
                organizationalUnit: "Identity KMS"
                locality: "Enschede"
                state: "Overijssel"
                country: "NL"
                email: "security@example.com"
                serialNumber: 42
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificates/issue:
    post:
      tags: [ Certificates ]
      summary: Issue a certificate
      operationId: issueCertificate
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/IssueCertificateRequest'
      responses:
        '200':
          description: Issued certificate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
              example:
                certificate: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="
                keyInfo:
                  key:
                    kty: "EC"
                    kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                    crv: "P-256"
                    x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                    y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                  kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                  alias: "tls-issuer-key"
                  providerId: "testsoftware"
                  signatureAlgorithm: "ECDSA_SHA256"
                  keyVisibility: "PUBLIC"
                  keyEncoding: "JOSE"
                  keyType: "EC"
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificates/issue-from-csr:
    post:
      tags: [ Certificates ]
      summary: Issue a certificate from a CSR
      operationId: issueCertificateFromCsr
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/IssueCertificateFromCsrRequest'
      responses:
        '200':
          description: Issued certificate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateResponse'
              example:
                certificate: "MIIBrTCCAVOgAwIBAgIBKzAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIA0qMoaE0kCw8wzpQdDty2oWpQ8Y9U7nXH9uwQdU3smlAiBvpTYZyM1aEYm8kA8xU+HmD2iMabvB8Oa3dY5yp3WBwA=="
                keyInfo:
                  key:
                    kty: "EC"
                    kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                    crv: "P-256"
                    x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                    y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                  kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                  alias: "tls-subject-key"
                  providerId: "testsoftware"
                  signatureAlgorithm: "ECDSA_SHA256"
                  keyVisibility: "PUBLIC"
                  keyEncoding: "JOSE"
                  keyType: "EC"
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificates:
    get:
      tags: [ Certificates ]
      summary: List trusted certificate aliases
      operationId: listTrustedCertificateAliases
      parameters:
        - name: providerId
          in: query
          required: false
          schema:
            type: string
          description: Optional provider whose certificate store should be used.
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Trusted certificate aliases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateAliasesResponse'
              example:
                aliases: [ "root-ca", "issuer-ca" ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificates/{alias}:
    parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
      - name: providerId
        in: query
        required: false
        schema:
          type: string
        description: Optional provider whose certificate store should be used.
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Certificates ]
      summary: Get a trusted certificate
      operationId: getTrustedCertificate
      responses:
        '200':
          description: Trusted certificate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateBytesResponse'
              example:
                certificate: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [ Certificates ]
      summary: Store a trusted certificate
      operationId: storeTrustedCertificate
      requestBody:
        $ref: '#/components/requestBodies/StoreCertificateRequest'
      responses:
        '201':
          description: Trusted certificate stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateBytesResponse'
              example:
                certificate: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags: [ Certificates ]
      summary: Delete a trusted certificate
      operationId: deleteTrustedCertificate
      responses:
        '204':
          description: Trusted certificate deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificate-chains:
    get:
      tags: [ Certificates ]
      summary: List certificate-chain aliases
      operationId: listCertificateChainAliases
      parameters:
        - name: providerId
          in: query
          required: false
          schema:
            type: string
          description: Optional provider whose certificate store should be used.
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: Certificate-chain aliases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateAliasesResponse'
              example:
                aliases: [ "issuer-chain", "wallet-trust-chain" ]
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /certificate-chains/{alias}:
    parameters:
      - name: alias
        in: path
        required: true
        schema:
          type: string
      - name: providerId
        in: query
        required: false
        schema:
          type: string
        description: Optional provider whose certificate store should be used.
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Certificates ]
      summary: Get a certificate chain
      operationId: getCertificateChain
      responses:
        '200':
          description: Certificate chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateChainResponse'
              example:
                certificates:
                  - "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="
                  - "MIIBjTCCATOgAwIBAgIBATAKBggqhkjOPQQDAjBqMQswCQYDVQQGEwJOTDERMA8GA1UECAwIT3Zlcmlqc3NlbDERMA8GA1UEBwwIRW5zY2hlZGUxEDAOBgNVBAoMB1NwaGVyZW9uMSMwIQYDVQQDDBpTcGhlcmVvbiBUZXN0IFJvb3QgQ0EgMjAyNjAeFw0yNjA2MTIwMDAwMDBaFw0zNjA2MTAwMDAwMDBaMGoxCzAJBgNVBAYTAk5MMREwDwYDVQQIDAhPdmVyaWpzc2VsMREwDwYDVQQHDAhFbnNjaGVkZTEQMA4GA1UECgwHU3BoZXJlb24xIzAhBgNVBAMMGlNwaGVyZW9uIFRlc3QgUm9vdCBDQSAyMDI2MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEl+6eLd0vAsKk6upt1WdQeCqvs6guVScSV8fGKPvR+nNkuq1/Cdlc+b+7OqQc0M+k9fn0Be6xdWPH1n/mHOzAKBggqhkjOPQQDAgNHADBEAiA8pT9o+0YQqE6ld7Y5RKu+U3ZlAiSZ8eR5rRQ0v8Wj1gIgRk89mJZ2Zj8vJZt+wa7YKk6mrG9Pj3Wf5db5hOMxXJQ="
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [ Certificates ]
      summary: Store a certificate chain
      operationId: storeCertificateChain
      requestBody:
        $ref: '#/components/requestBodies/StoreCertificateChainRequest'
      responses:
        '201':
          description: Certificate chain stored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificateChainResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags: [ Certificates ]
      summary: Delete a certificate chain
      operationId: deleteCertificateChain
      responses:
        '204':
          description: Certificate chain deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /signatures/raw/create:
    post:
      tags: [ Signatures ]
      summary: Create a raw signature
      description: >
        Produces a raw (detached) cryptographic signature over the supplied bytes using a
        managed key. The request body identifies the key with a `keyInfo` (by `providerId`
        plus either `alias` or `kid`) and carries the bytes to sign in `input` as a
        base64-encoded string; the signature algorithm is taken from the resolved key. The
        response returns the signature bytes, base64-encoded; only the signature is returned,
        not the input. Pass the same `input` and `keyInfo` to `/signatures/raw/verify`.
        Returns 400 if the key cannot be found.
      operationId: createRawSignature
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/CreateRawSignatureRequest'
      responses:
        '201':
          description: Signature created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRawSignatureResponse'
              example:
                signature: "MEUCIQDx1c0r2k1mWmExampleSignatureBytesBase64EncodedAA"
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /signatures/raw/verify:
    post:
      tags: [ Signatures ]
      summary: Verify a raw signature
      description: >
        Verifies a raw (detached) signature against the original bytes using a managed
        key. The request body carries the `keyInfo` identifying the verifying key, the
        original bytes in `input` (base64), and the candidate `signature` (base64). The
        response is `{ "isValid": true }` when the signature matches and
        `{ "isValid": false }` when it does not (for example when the input was tampered
        with). Verification failures due to a wrong signature return 200 with
        `isValid: false`, not an error status. Returns 400 only for malformed input.
      operationId: isValidRawSignature
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/VerifyRawSignatureRequest'
      responses:
        '200':
          description: Signature verification performed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyRawSignatureResponse'
              example:
                isValid: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /resolvers:
    get:
      tags: [ Resolvers ]
      summary: List all configured key resolvers
      description: >
        Returns every key resolver configured for the calling tenant. A key resolver turns
        a key reference (a JWK, kid, X.509 chain, or DID) into a concrete public key. Each
        resolver advertises which identifier methods and key types it supports. The default
        deployment exposes a resolver with id `jose_cose_resolver`.
      operationId: listResolvers
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: A list of Key Resolver configurations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResolversResponse'
              example:
                resolvers:
                  - resolverId: "jose_cose_resolver"
                    supportedIdentifierMethods: [ "JWK", "KID", "COSE_KEY", "X5C", "DID" ]
                    supportedKeyTypes: [ "EC", "RSA", "OKP" ]

  /resolvers/{resolverId}:
    parameters:
      - $ref: '#/components/parameters/ResolverId'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ Resolvers ]
      summary: Get key resolver details
      description: >
        Returns the configuration of a single key resolver identified by its
        `resolverId` path parameter (for example `jose_cose_resolver`), including the
        identifier methods and key types it supports. Returns 404 if no resolver with
        that id is configured for the calling tenant.
      operationId: getResolver
      responses:
        '200':
          description: Key Resolver details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyResolver'
              example:
                resolverId: "jose_cose_resolver"
                supportedIdentifierMethods: [ "JWK", "KID", "COSE_KEY", "X5C", "DID" ]
                supportedKeyTypes: [ "EC", "RSA", "OKP" ]
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /resolvers/{resolverId}/resolve:
    parameters:
      - $ref: '#/components/parameters/ResolverId'
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    post:
      tags: [ Resolvers ]
      summary: Resolve a public key
      description: >
        Resolves a public key through the resolver identified by `resolverId` (for
        example `jose_cose_resolver`). The request body carries a `keyInfo` reference to
        resolve, an optional `identifierMethod` (for example `JWK`, `KID`, `DID`,
        `X5C`) hinting how to interpret it, optional `trustedCerts`, and an optional
        `verifyX509CertificateChain` flag. The response is a fully resolved key whose
        public `key` JWK is guaranteed to be present. Returns 404 if the resolver id is
        unknown, or 400 if the key reference cannot be resolved.
      operationId: resolveKey
      requestBody:
        $ref: '#/components/requestBodies/ResolvePublicKeyRequest'
      responses:
        '200':
          description: Key resolved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedKeyInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /keys:
    get:
      tags: [ KMS ]
      summary: List all managed cryptographic keys across all providers
      description: >
        Lists key metadata across every provider configured for the calling tenant.
        Only metadata is returned (alias, kid, algorithm, type); private key material is
        never included. Pass the optional `providerId` query parameter to restrict the
        listing to a single provider. Results are scoped to the calling tenant only.
      operationId: listKeys
      parameters:
        - name: providerId
          in: query
          required: false
          schema:
            type: string
          description: Optional provider ID to filter keys by provider.
          example: "testsoftware"
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      responses:
        '200':
          description: A list of all managed keys
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListKeysResponse'
              example:
                keyInfos:
                  - kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                    alias: "my-signing-key"
                    providerId: "testsoftware"
                    signatureAlgorithm: "ECDSA_SHA256"
                    keyVisibility: "PUBLIC"
                    keyEncoding: "JOSE"
                    keyType: "EC"
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [ KMS ]
      summary: Generate a new key (provider chosen from body or default)
      description: >
        Generates a new key. The request body selects the signature algorithm
        (for example `ECDSA_SHA256`) and may optionally include an `alias`, `use`,
        `keyOperations`, and a `providerId`. If `providerId` is omitted the default
        provider is used. The response contains the generated key pair including its
        `kid`, `alias`, and the public JWK. Returns 400 if the requested algorithm or
        provider is not available.
      operationId: generateKey
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/GenerateKeyGlobalRequest'
      responses:
        '201':
          description: Key generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateKeyResponse'
              example:
                keyPair:
                  kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                  providerId: "testsoftware"
                  alias: "my-signing-key"
                  jose:
                    publicJwk:
                      kty: "EC"
                      kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                      crv: "P-256"
                      x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                      y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                  cose:
                    publicCoseKey:
                      kty: 2
                      crv: 1
                      x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                      y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /keys/import:
    post:
      tags: [ KMS ]
      summary: Import externally supplied key material (provider taken from keyInfo)
      description: >
        Imports a key you already hold into the KMS. The target provider is taken from
        the `providerId` inside the body's `keyInfo` (for example `testsoftware`), and
        the alias likewise comes from `keyInfo.alias`. The body must carry a fully
        resolved `keyInfo` (the `key` JWK is required). Returns 400 if the keyInfo is
        missing required fields or names an unknown provider.
      operationId: importKey
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/ImportKeyByInfoRequest'
      responses:
        '201':
          description: Key imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportKeyResponse'
              example:
                keyInfo:
                  key:
                    kty: "EC"
                    kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                    crv: "P-256"
                    x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                    y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                  kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                  alias: "my-signing-key"
                  providerId: "testsoftware"
                  signatureAlgorithm: "ECDSA_SHA256"
                  keyVisibility: "PUBLIC"
                  keyEncoding: "JOSE"
                  keyType: "EC"
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /keys/register:
    post:
      tags: [ KMS ]
      summary: Register an existing provider key for platform use
      description: >
        Explicitly onboards a key that already exists inside a provider into the
        platform's persistent key reference store, so the platform can discover and use
        it later. The body identifies the key by its `providerId` and `alias`, with an
        optional `kid`. This does not create or import key material; the key must already
        live in the named provider. The response confirms registration and echoes the
        alias, providerId, and kid. Returns 400 if the provider or key cannot be found.
      operationId: registerKeyReference
      parameters:
        - $ref: './common-components.yml#/components/parameters/UserId'
        - $ref: './common-components.yml#/components/parameters/TenantId'
      requestBody:
        $ref: '#/components/requestBodies/RegisterKeyReferenceRequest'
      responses:
        '201':
          description: Key reference registered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterKeyReferenceResponse'
              example:
                registered: true
                alias: "my-signing-key"
                providerId: "testsoftware"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'

  /keys/{aliasOrKid}:
    parameters:
      - $ref: '#/components/parameters/AliasOrKid'
      - name: providerId
        in: query
        required: false
        schema:
          type: string
        description: Optional provider ID to restrict the lookup to a single provider.
        example: "testsoftware"
      - $ref: './common-components.yml#/components/parameters/UserId'
      - $ref: './common-components.yml#/components/parameters/TenantId'
    get:
      tags: [ KMS ]
      summary: Get a specific managed key by alias or kid
      description: >
        Looks up a single key across the calling tenant's providers by its alias or kid.
        The `aliasOrKid` path parameter may be the alias (for example
        `my-signing-key`) or the kid (for example
        `00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE`). Pass the optional `providerId`
        query parameter to disambiguate when the same alias exists in more than one
        provider. Returns 404 if no matching key is found.
      operationId: getKey
      responses:
        '200':
          description: The managed key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKeyResponse'
              example:
                keyInfo:
                  key:
                    kty: "EC"
                    kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                    crv: "P-256"
                    x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                    y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                  kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                  alias: "my-signing-key"
                  providerId: "testsoftware"
                  signatureAlgorithm: "ECDSA_SHA256"
                  keyVisibility: "PUBLIC"
                  keyEncoding: "JOSE"
                  keyType: "EC"
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags: [ KMS ]
      summary: Delete a key from the key store by alias or kid
      description: >
        Permanently removes a key identified by `aliasOrKid` (its alias or kid) from the
        calling tenant's key store. Pass the optional `providerId` query parameter to
        scope the deletion to a single provider. Returns 204 with no body on success, or
        404 if no matching key exists.
      operationId: deleteKey
      responses:
        '204':
          description: Key deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'

components:
  securitySchemes:
    bearer:
      $ref: './common-components.yml#/components/securitySchemes/bearer'
  parameters:
    # ── Re-exported path parameters from kms-components.yml ──
    ProviderId:
      $ref: './kms-components.yml#/components/parameters/ProviderId'
    AliasOrKid:
      $ref: './kms-components.yml#/components/parameters/AliasOrKid'
    ResolverId:
      $ref: './kms-components.yml#/components/parameters/ResolverId'
  requestBodies:
    CreateKeyProviderRequest:
      description: Request body for creating a new Key Provider.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateKeyProvider'

    UpdateKeyProviderRequest:
      description: Request body for updating an existing Key Provider.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateKeyProvider'

    GenerateKeyRequest:
      description: Request body for generating a new key in a specific provider.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerateKey'
          example:
            alias: "my-signing-key"
            use: "sig"
            alg: "ECDSA_SHA256"
            keyOperations: [ "sign" ]

    CreateSimpleSignatureRequest:
      description: Request body for creating a digital signature.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateSimpleSignature'

    VerifySimpleSignatureRequest:
      description: Request body for verifying a digital signature.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifySimpleSignature'

    CreateRawSignatureRequest:
      description: >
        Request body for creating a raw signature. `keyInfo` identifies the signing key by
        `providerId` plus either `alias` or `kid` (the same way the server looks the key up);
        the signature algorithm is taken from the resolved key. `input` is the base64-encoded
        payload to sign. The example signs the bytes of the string "hello" (base64 `aGVsbG8=`).
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateRawSignature'
          example:
            keyInfo:
              providerId: "testsoftware"
              alias: "my-signing-key"
            input: "aGVsbG8="

    VerifyRawSignatureRequest:
      description: >
        Request body for verifying a raw signature. `keyInfo` identifies the verifying key by
        `providerId` plus either `alias` or `kid`, `input` is the base64-encoded original
        payload, and `signature` is the base64-encoded signature returned by the create
        endpoint. The signature value below is illustrative; use the value returned for your
        own key and input.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifyRawSignature'
          example:
            keyInfo:
              providerId: "testsoftware"
              alias: "my-signing-key"
            input: "aGVsbG8="
            signature: "MEUCIQDx1c0r2k1mWmExampleSignatureBytesBase64EncodedAA"

    ImportKeyRequest:
      description: >
        Request body for importing externally supplied key material into a provider. The
        `keyInfo.key` JWK carries the actual key material (the example below imports a
        P-256 EC key).
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ImportKey'
          example:
            keyInfo:
              key:
                kty: "EC"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                use: "sig"
                key_ops: [ "sign" ]
                crv: "P-256"
                x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                d: "P_4YEyuDj4aA4IVYVku4dm3BoDReFTKVsBwb1utoWCQ"
              kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
              alias: "my-signing-key"
              providerId: "testsoftware"
              signatureAlgorithm: "ECDSA_SHA256"
              keyVisibility: "PUBLIC"
              keyEncoding: "JOSE"
              keyType: "EC"

    ResolvePublicKeyRequest:
      description: >
        Request body for resolving a public key. `keyInfo` carries only the reference to
        resolve, never the key material itself (resolution is what produces the key). For a
        managed key that is the `providerId` plus either `alias` or `kid`; for an external
        key it can be an X.509 chain in `x5c` or a DID. `identifierMethod` optionally hints
        how to interpret the reference. The example resolves a managed key by its `alias`.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResolvePublicKey'
          example:
            keyInfo:
              providerId: "testsoftware"
              alias: "my-signing-key"

    ImportKeyByInfoRequest:
      description: >
        Request body for importing externally supplied key material where the target provider
        and alias are taken from the body's `keyInfo` (`keyInfo.providerId` and
        `keyInfo.alias`) rather than from the URL.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ImportKey'
          example:
            keyInfo:
              key:
                kty: "EC"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                use: "sig"
                key_ops: [ "sign" ]
                crv: "P-256"
                x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                d: "P_4YEyuDj4aA4IVYVku4dm3BoDReFTKVsBwb1utoWCQ"
              kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
              alias: "my-signing-key"
              providerId: "testsoftware"
              signatureAlgorithm: "ECDSA_SHA256"
              keyVisibility: "PUBLIC"
              keyEncoding: "JOSE"
              keyType: "EC"

    GenerateKeyGlobalRequest:
      description: >
        Request body for generating a key without targeting a provider in the URL. The
        optional `providerId` chooses the provider; if omitted the default provider is
        used.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerateKeyGlobal'
          example:
            alias: "my-signing-key"
            use: "sig"
            alg: "ECDSA_SHA256"
            keyOperations: [ "sign" ]
            providerId: "testsoftware"

    RegisterKeyReferenceRequest:
      description: Request body for registering an existing provider key for platform use.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RegisterKeyReferenceRequest'
          example:
            providerId: "testsoftware"
            alias: "my-signing-key"
            kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"

    ProviderQueryRequest:
      description: Request body for querying providers by capability.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProviderQuery'
          example:
            operation: "ENCRYPT"
            contentEncryptionAlgorithm: "A256GCM"
            providerType: "software"

    EncryptRequest:
      description: Request body for encrypting bytes.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EncryptRequest'
          example:
            keyInfo:
              providerId: "testsoftware"
              alias: "encryption-key"
            plaintext: "aGVsbG8="
            algorithm: "A256GCM"

    DecryptRequest:
      description: Request body for decrypting bytes.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DecryptRequest'
          example:
            keyInfo:
              providerId: "testsoftware"
              alias: "encryption-key"
            ciphertext: "8rj9iBf2Vv5uQmE="
            algorithm: "A256GCM"
            iv: "QkM0hQDUzC7Vqvut"
            authTag: "t6YF2+0M0vO7vKq9Qh7uQg=="

    WrapKeyRequest:
      description: Request body for wrapping key material.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WrapKeyRequest'
          example:
            wrappingKeyInfo:
              providerId: "testsoftware"
              alias: "key-wrap-key"
            keyToWrap: "MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE="
            algorithm: "A256KW"

    UnwrapKeyRequest:
      description: Request body for unwrapping key material.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnwrapKeyRequest'
          example:
            unwrappingKeyInfo:
              providerId: "testsoftware"
              alias: "key-wrap-key"
            wrappedKey: "q83vEj6GTdS3BzN9vdS6F4x1j9p5vQ=="
            algorithm: "A256KW"

    KeyAgreementRequest:
      description: Request body for deriving a shared secret.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/KeyAgreementRequest'
          example:
            privateKeyInfo:
              providerId: "testsoftware"
              alias: "holder-x25519-private"
            publicKeyInfo:
              key:
                kty: "OKP"
                crv: "X25519"
                x: "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"
              kid: "peer-x25519-public"
              providerId: "testsoftware"
              keyVisibility: "PUBLIC"
              keyEncoding: "JOSE"
              keyType: "OKP"
            algorithm: "ECDH_ES"
            keyDataLen: 256

    GenerateCertificateSigningRequestRequest:
      description: Request body for generating a certificate signing request.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenerateCertificateSigningRequestRequest'
          example:
            subjectKeyInfo:
              key:
                kty: "EC"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                use: "sig"
                key_ops: [ "sign" ]
                crv: "P-256"
                x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
                d: "P_4YEyuDj4aA4IVYVku4dm3BoDReFTKVsBwb1utoWCQ"
              kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
              alias: "tls-subject-key"
              providerId: "testsoftware"
              signatureAlgorithm: "ECDSA_SHA256"
              keyVisibility: "PRIVATE"
              keyEncoding: "JOSE"
              keyType: "EC"
            subject:
              commonName: "adapter-test.example.com"
              organizationName: "Sphereon"
              organizationUnit: "Identity KMS"
              locality: "Enschede"
              state: "Overijssel"
              country: "NL"
              email: "security@example.com"
            serialNumber: 42

    IssueCertificateRequest:
      description: Request body for issuing a certificate.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IssueCertificateRequest'
          example:
            issuerKeyInfo:
              providerId: "testsoftware"
              alias: "root-ca-key"
            issuer:
              commonName: "Sphereon Test Root CA 2026"
              organizationName: "Sphereon"
              country: "NL"
            subjectKeyInfo:
              key:
                kty: "EC"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                crv: "P-256"
                x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
              kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
              alias: "tls-subject-key"
              providerId: "testsoftware"
              signatureAlgorithm: "ECDSA_SHA256"
              keyVisibility: "PUBLIC"
              keyEncoding: "JOSE"
              keyType: "EC"
            subject:
              commonName: "adapter-test.example.com"
              organizationName: "Sphereon"
              country: "NL"
            serialNumber: 43
            notBefore: "2026-06-12T00:00:00"
            notAfter: "2027-06-12T00:00:00"

    IssueCertificateFromCsrRequest:
      description: Request body for issuing a certificate from a CSR.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IssueCertificateFromCsrRequest'
          example:
            issuerKeyInfo:
              providerId: "testsoftware"
              alias: "root-ca-key"
            issuer:
              commonName: "Sphereon Test Root CA 2026"
              organizationName: "Sphereon"
              country: "NL"
            subjectKeyInfo:
              key:
                kty: "EC"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                crv: "P-256"
                x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
              kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
              alias: "tls-subject-key"
              providerId: "testsoftware"
              signatureAlgorithm: "ECDSA_SHA256"
              keyVisibility: "PUBLIC"
              keyEncoding: "JOSE"
              keyType: "EC"
            csr:
              der: "MIIBKDCBzwIBADCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7oAAwCgYIKoZIzj0EAwIDSAAwRQIhAMiJjZ9Z5w8L7V2qO5n3YgO4Q3t4V6qIh3e3c4C5l7vDAiBd9c0r2k1mWm7y6iY9fKq8pC4d2x3v5z6a7b8c9d0e1g=="
              commonName: "adapter-test.example.com"
              organization: "Sphereon"
              organizationalUnit: "Identity KMS"
              locality: "Enschede"
              state: "Overijssel"
              country: "NL"
              email: "security@example.com"
              serialNumber: 42
            serialNumber: 44
            notBefore: "2026-06-12T00:00:00"
            notAfter: "2027-06-12T00:00:00"

    StoreCertificateRequest:
      description: Request body for storing a trusted certificate.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StoreCertificateRequest'
          example:
            certificate: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="

    StoreCertificateChainRequest:
      description: Request body for storing a certificate chain.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StoreCertificateChainRequest'
          example:
            certificates:
              - "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="
              - "MIIBjTCCATOgAwIBAgIBATAKBggqhkjOPQQDAjBqMQswCQYDVQQGEwJOTDERMA8GA1UECAwIT3Zlcmlqc3NlbDERMA8GA1UEBwwIRW5zY2hlZGUxEDAOBgNVBAoMB1NwaGVyZW9uMSMwIQYDVQQDDBpTcGhlcmVvbiBUZXN0IFJvb3QgQ0EgMjAyNjAeFw0yNjA2MTIwMDAwMDBaFw0zNjA2MTAwMDAwMDBaMGoxCzAJBgNVBAYTAk5MMREwDwYDVQQIDAhPdmVyaWpzc2VsMREwDwYDVQQHDAhFbnNjaGVkZTEQMA4GA1UECgwHU3BoZXJlb24xIzAhBgNVBAMMGlNwaGVyZW9uIFRlc3QgUm9vdCBDQSAyMDI2MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEl+6eLd0vAsKk6upt1WdQeCqvs6guVScSV8fGKPvR+nNkuq1/Cdlc+b+7OqQc0M+k9fn0Be6xdWPH1n/mHOzAKBggqhkjOPQQDAgNHADBEAiA8pT9o+0YQqE6ld7Y5RKu+U3ZlAiSZ8eR5rRQ0v8Wj1gIgRk89mJZ2Zj8vJZt+wa7YKk6mrG9Pj3Wf5db5hOMxXJQ="
            keyInfo:
              key:
                kty: "EC"
                kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
                crv: "P-256"
                x: "HFL67WWh6PYWKOy1mzt9Y2ANs-CWFIyVtouR-Jx_mAM"
                y: "9f_1x7fwUuEbEwxSNTYE3jQF-zForWpKkEMpiUp1MNI"
              kid: "00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE"
              alias: "tls-subject-key"
              providerId: "testsoftware"
              signatureAlgorithm: "ECDSA_SHA256"
              keyVisibility: "PUBLIC"
              keyEncoding: "JOSE"
              keyType: "EC"

  responses:
    BadRequest:
      description: Bad request due to invalid input parameters or request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    InternalServerError:
      description: An unexpected error occurred on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

  schemas:
    # ── Re-exported entity schemas from kms-components.yml ──
    AwsAssumeRoleCredentials:
      $ref: './kms-components.yml#/components/schemas/AwsAssumeRoleCredentials'
    AwsClientConfiguration:
      $ref: './kms-components.yml#/components/schemas/AwsClientConfiguration'
    AwsKmsSetting:
      $ref: './kms-components.yml#/components/schemas/AwsKmsSetting'
    AwsStaticCredentials:
      $ref: './kms-components.yml#/components/schemas/AwsStaticCredentials'
    AwsWebIdentityTokenCredentials:
      $ref: './kms-components.yml#/components/schemas/AwsWebIdentityTokenCredentials'
    AzureClientSecretCredentialOpts:
      $ref: './kms-components.yml#/components/schemas/AzureClientSecretCredentialOpts'
    AzureCredentialOpts:
      $ref: './kms-components.yml#/components/schemas/AzureCredentialOpts'
    AzureKeyVaultSetting:
      $ref: './kms-components.yml#/components/schemas/AzureKeyVaultSetting'
    CoseKeyPair:
      $ref: './kms-components.yml#/components/schemas/CoseKeyPair'
    CreateKeyProvider:
      description: Request body for creating a new Key Provider instance.
      type: object
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/KeyProviderType'
        azureKeyvaultSettings:
          $ref: '#/components/schemas/AzureKeyVaultSetting'
        awsKmsSettings:
          $ref: '#/components/schemas/AwsKmsSetting'
        cacheEnabled:
          type: boolean
          description: Whether to enable caching for keys retrieved from this provider.
          default: false
        cacheTTLInSeconds:
          type: integer
          format: int32
          description: Time-to-live for cached keys in seconds (if cacheEnabled is true).
          default: 300
          minimum: 0

    CreateRawSignature:
      description: Request body for creating a raw signature.
      type: object
      required:
        - keyInfo
        - input
      properties:
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        input:
          type: string
          format: byte
          description: The bytes to sign, base64-encoded. The example is the string "hello".
          example: "aGVsbG8="

    CreateSimpleSignature:
      description: Request body for creating a digital signature.
      type: object
      required:
        - signInput
        - keyInfo
      properties:
        signInput:
          $ref: '#/components/schemas/SignInput'
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        signatureAlgorithm:
          $ref: '#/components/schemas/SignatureAlgorithm'

    CryptoAlg:
      $ref: './kms-components.yml#/components/schemas/CryptoAlg'
    Curve:
      $ref: './kms-components.yml#/components/schemas/Curve'
    DigestAlg:
      $ref: './kms-components.yml#/components/schemas/DigestAlg'
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code identifying the type of error.
          example: "NOT_FOUND"
        message:
          type: string
          description: Human-readable error message.
          example: "No key found for alias or kid '00-qTBov6GxjPSuMNxnk876cMP0JKjbwl4ZyN_sY2tE'"
        details:
          type: object
          description: Additional error details.
          additionalProperties: true

    KmsProviderOperation:
      type: string
      enum:
        - IMPORT_KEY
        - EXPORT_KEY
        - GENERATE_KEY
        - DELETE_KEY
        - SIGN
        - VERIFY
        - ENCRYPT
        - DECRYPT
        - WRAP_KEY
        - UNWRAP_KEY
        - KEY_AGREEMENT
        - GENERATE_CERTIFICATE
        - IMPORT_CERTIFICATE
        - X509_CHAIN_VALIDATION
        - GENERATE_MAC
        - VERIFY_MAC
        - HARDWARE_BACKED
        - ATTESTATION

    KeyStorageType:
      type: string
      enum:
        - NONE
        - EPHEMERAL
        - PERSISTENT
        - HARDWARE

    ContentEncryptionAlgorithm:
      type: string
      enum:
        - A128GCM
        - A192GCM
        - A256GCM
        - A128CBC_HS256
        - A192CBC_HS384
        - A256CBC_HS512
      example: A256GCM

    KeyWrapAlgorithm:
      type: string
      enum:
        - RSA1_5
        - RSA_OAEP
        - RSA_OAEP_256
        - RSA_OAEP_384
        - RSA_OAEP_512
        - A128KW
        - A192KW
        - A256KW
        - A128GCMKW
        - A192GCMKW
        - A256GCMKW
        - DIR
      example: A256KW

    KeyAgreementAlgorithm:
      type: string
      enum:
        - ECDH_ES
        - ECDH_ES_A128KW
        - ECDH_ES_A192KW
        - ECDH_ES_A256KW
      example: ECDH_ES

    OperationCapability:
      type: object
      description: Support statement for one KMS operation on a provider.
      required:
        - operation
        - supported
      properties:
        operation:
          $ref: '#/components/schemas/KmsProviderOperation'
        supported:
          type: boolean
          description: Whether this provider supports the operation.
          example: true
        signatureAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/SignatureAlgorithm'
        contentEncryptionAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/ContentEncryptionAlgorithm'
        keyWrapAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/KeyWrapAlgorithm'
        keyAgreementAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/KeyAgreementAlgorithm'
        notes:
          type: string
          description: Optional provider-specific limitations or implementation notes.
          example: "AES-GCM content encryption is backed by the provider key store."

    ProviderCapabilities:
      type: object
      description: Full capability report for a KMS provider.
      required:
        - providerId
        - providerType
        - storageTypes
        - supportsKeyImport
        - supportsKeyExport
        - exposePrivateKeys
        - operations
        - supportedKeyTypes
        - supportedCurves
        - supportedCryptoAlgorithms
        - supportedDigestAlgorithms
        - signatureAlgorithms
        - contentEncryptionAlgorithms
        - supportsX509
        - supportsAttestation
        - supportsHardwareBacking
        - supportsPublicKeyResolution
        - resolutionMethods
      properties:
        providerId:
          type: string
          description: Stable identifier of the provider.
          example: "testsoftware"
        providerType:
          type: string
          description: Provider implementation type.
          example: "software"
        storageTypes:
          type: array
          items:
            $ref: '#/components/schemas/KeyStorageType'
        supportsKeyImport:
          type: boolean
        supportsKeyExport:
          type: boolean
        exposePrivateKeys:
          type: boolean
        operations:
          type: array
          items:
            $ref: '#/components/schemas/OperationCapability'
        supportedKeyTypes:
          type: array
          items:
            $ref: '#/components/schemas/KeyType'
        supportedCurves:
          type: array
          items:
            $ref: '#/components/schemas/Curve'
        supportedCryptoAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/CryptoAlg'
        supportedDigestAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/DigestAlg'
        signatureAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/SignatureAlgorithm'
        contentEncryptionAlgorithms:
          type: array
          items:
            $ref: '#/components/schemas/ContentEncryptionAlgorithm'
        supportsX509:
          type: boolean
        supportsAttestation:
          type: boolean
        supportsHardwareBacking:
          type: boolean
        supportsPublicKeyResolution:
          type: boolean
        resolutionMethods:
          type: array
          items:
            type: string

    ProviderCapabilitiesResponse:
      type: object
      description: Capability report wrapper keyed by provider ID.
      required:
        - providerId
        - capabilities
      properties:
        providerId:
          type: string
          example: "testsoftware"
        capabilities:
          $ref: '#/components/schemas/ProviderCapabilities'

    ListCapabilitiesResponse:
      type: object
      description: Capability reports for all configured KMS providers.
      required:
        - providers
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ProviderCapabilitiesResponse'

    ProviderQuery:
      type: object
      description: Criteria used to select KMS providers by operation, algorithm, storage, and security requirements.
      properties:
        operation:
          $ref: '#/components/schemas/KmsProviderOperation'
        cryptoAlgorithm:
          $ref: '#/components/schemas/CryptoAlg'
        digestAlgorithm:
          $ref: '#/components/schemas/DigestAlg'
        signatureAlgorithm:
          $ref: '#/components/schemas/SignatureAlgorithm'
        contentEncryptionAlgorithm:
          $ref: '#/components/schemas/ContentEncryptionAlgorithm'
        curve:
          $ref: '#/components/schemas/Curve'
        keyType:
          $ref: '#/components/schemas/KeyType'
        storageType:
          $ref: '#/components/schemas/KeyStorageType'
        requiresHardwareBacking:
          type: boolean
          default: false
          description: Require the provider to store keys in hardware-backed storage.
          example: false
        requiresAttestation:
          type: boolean
          default: false
          description: Require the provider to support key attestation.
          example: false
        requiresKeyExport:
          type: boolean
          default: false
          description: Require private or symmetric key export support.
          example: false
        requiresKeyImport:
          type: boolean
          default: false
          description: Require externally supplied key material import support.
          example: true
        identifierMethod:
          $ref: '#/components/schemas/IdentifierMethod'
        providerType:
          type: string
          description: Optional provider implementation type filter.
          example: "software"

    ProviderMatch:
      type: object
      description: Provider selected by a capability query.
      required:
        - providerId
        - matchScore
      properties:
        providerId:
          type: string
          example: "testsoftware"
        capabilities:
          $ref: '#/components/schemas/ProviderCapabilities'
        matchScore:
          type: integer
          format: int32
          default: 100
          description: Relative match quality. Higher is better.
          example: 100

    QueryProvidersResponse:
      type: object
      description: Result set for a provider capability query.
      required:
        - matches
        - totalProviders
        - matchCount
      properties:
        matches:
          type: array
          items:
            $ref: '#/components/schemas/ProviderMatch'
        totalProviders:
          type: integer
          format: int32
          description: Number of providers evaluated.
          example: 2
        matchCount:
          type: integer
          format: int32
          description: Number of providers matching the query.
          example: 1

    QueryBestProviderResponse:
      type: object
      properties:
        match:
          $ref: '#/components/schemas/ProviderMatch'

    EncryptRequest:
      type: object
      description: Request to encrypt plaintext bytes with a KMS-managed key.
      required:
        - keyInfo
        - plaintext
        - algorithm
      properties:
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        plaintext:
          type: string
          format: byte
          description: Plaintext bytes to encrypt, base64-encoded. Example is "hello".
          example: "aGVsbG8="
        algorithm:
          $ref: '#/components/schemas/ContentEncryptionAlgorithm'
        additionalAuthenticatedData:
          type: string
          format: byte
          description: Optional additional authenticated data for AEAD algorithms, base64-encoded.
          example: "dGVuYW50PWFjbWU="

    EncryptResponse:
      type: object
      description: Ciphertext and AEAD parameters produced by encryption.
      required:
        - ciphertext
        - iv
        - authTag
      properties:
        ciphertext:
          type: string
          format: byte
          description: Encrypted bytes, base64-encoded.
          example: "8rj9iBf2Vv5uQmE="
        iv:
          type: string
          format: byte
          description: Initialization vector or nonce, base64-encoded.
          example: "QkM0hQDUzC7Vqvut"
        authTag:
          type: string
          format: byte
          description: Authentication tag for AEAD algorithms, base64-encoded.
          example: "t6YF2+0M0vO7vKq9Qh7uQg=="

    DecryptRequest:
      type: object
      description: Request to decrypt ciphertext bytes with a KMS-managed key.
      required:
        - keyInfo
        - ciphertext
        - algorithm
        - iv
        - authTag
      properties:
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        ciphertext:
          type: string
          format: byte
          description: Ciphertext bytes to decrypt, base64-encoded.
          example: "8rj9iBf2Vv5uQmE="
        algorithm:
          $ref: '#/components/schemas/ContentEncryptionAlgorithm'
        iv:
          type: string
          format: byte
          description: Initialization vector or nonce returned by encryption, base64-encoded.
          example: "QkM0hQDUzC7Vqvut"
        authTag:
          type: string
          format: byte
          description: Authentication tag returned by encryption, base64-encoded.
          example: "t6YF2+0M0vO7vKq9Qh7uQg=="
        additionalAuthenticatedData:
          type: string
          format: byte
          description: Optional AEAD additional authenticated data, base64-encoded. Must match the value used for encryption.
          example: "dGVuYW50PWFjbWU="

    DecryptResponse:
      type: object
      description: Decrypted plaintext bytes.
      required:
        - plaintext
      properties:
        plaintext:
          type: string
          format: byte
          description: Decrypted plaintext bytes, base64-encoded. Example is "hello".
          example: "aGVsbG8="

    WrapKeyRequest:
      type: object
      description: Request to wrap raw key material with a KMS-managed wrapping key.
      required:
        - wrappingKeyInfo
        - keyToWrap
        - algorithm
      properties:
        wrappingKeyInfo:
          $ref: '#/components/schemas/KeyInfo'
        keyToWrap:
          type: string
          format: byte
          description: Raw key material to wrap, base64-encoded.
          example: "MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE="
        algorithm:
          $ref: '#/components/schemas/KeyWrapAlgorithm'

    WrapKeyResponse:
      type: object
      description: Wrapped key material.
      required:
        - wrappedKey
      properties:
        wrappedKey:
          type: string
          format: byte
          description: Wrapped key bytes, base64-encoded.
          example: "q83vEj6GTdS3BzN9vdS6F4x1j9p5vQ=="

    UnwrapKeyRequest:
      type: object
      description: Request to unwrap key material with a KMS-managed unwrapping key.
      required:
        - unwrappingKeyInfo
        - wrappedKey
        - algorithm
      properties:
        unwrappingKeyInfo:
          $ref: '#/components/schemas/KeyInfo'
        wrappedKey:
          type: string
          format: byte
          description: Wrapped key bytes returned by the wrap operation, base64-encoded.
          example: "q83vEj6GTdS3BzN9vdS6F4x1j9p5vQ=="
        algorithm:
          $ref: '#/components/schemas/KeyWrapAlgorithm'

    UnwrapKeyResponse:
      type: object
      description: Unwrapped raw key material.
      required:
        - unwrappedKey
      properties:
        unwrappedKey:
          type: string
          format: byte
          description: Raw unwrapped key bytes, base64-encoded.
          example: "MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MDE="

    KeyAgreementRequest:
      type: object
      description: Request to derive a shared secret from a private key and peer public key.
      required:
        - privateKeyInfo
        - publicKeyInfo
        - algorithm
      properties:
        privateKeyInfo:
          $ref: '#/components/schemas/KeyInfo'
        publicKeyInfo:
          $ref: '#/components/schemas/KeyInfo'
        algorithm:
          $ref: '#/components/schemas/KeyAgreementAlgorithm'
        keyDataLen:
          type: integer
          format: int32
          description: Desired shared secret length in bits.
          example: 256

    KeyAgreementResponse:
      type: object
      description: Shared secret derived by key agreement.
      required:
        - sharedSecret
      properties:
        sharedSecret:
          type: string
          format: byte
          description: Derived shared secret bytes, base64-encoded.
          example: "oN1hJdAhtf3SW+pm1da4DyxLSFhP0YE6FnW9EeYk7rk="

    X509DistinguishedName:
      type: object
      description: X.509 subject or issuer distinguished name fields.
      properties:
        commonName:
          type: string
          example: "adapter-test.example.com"
        organizationName:
          type: string
          example: "Sphereon"
        organizationUnit:
          type: string
          example: "Identity KMS"
        locality:
          type: string
          example: "Enschede"
        state:
          type: string
          example: "Overijssel"
        country:
          type: string
          example: "NL"
        email:
          type: string
          example: "security@example.com"

    GenerateCertificateSigningRequestRequest:
      type: object
      description: Request to generate a CSR for a resolved subject key.
      required:
        - subjectKeyInfo
        - subject
      properties:
        subjectKeyInfo:
          $ref: '#/components/schemas/ResolvedKeyInfo'
        subject:
          $ref: '#/components/schemas/X509DistinguishedName'
        serialNumber:
          type: integer
          format: int32
          default: 1
          example: 42

    CertificateSigningRequestResponse:
      type: object
      description: DER-encoded CSR and parsed distinguished name fields.
      required:
        - der
      properties:
        der:
          type: string
          format: byte
          description: DER-encoded CSR, base64-encoded.
          example: "MIIBKDCBzwIBADCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7oAAwCgYIKoZIzj0EAwIDSAAwRQIhAMiJjZ9Z5w8L7V2qO5n3YgO4Q3t4V6qIh3e3c4C5l7vDAiBd9c0r2k1mWm7y6iY9fKq8pC4d2x3v5z6a7b8c9d0e1g=="
        commonName:
          type: string
          example: "adapter-test.example.com"
        organization:
          type: string
          example: "Sphereon"
        organizationalUnit:
          type: string
          example: "Identity KMS"
        locality:
          type: string
          example: "Enschede"
        state:
          type: string
          example: "Overijssel"
        country:
          type: string
          example: "NL"
        email:
          type: string
          example: "security@example.com"
        serialNumber:
          type: integer
          format: int32
          example: 42

    CertificateSigningRequest:
      type: object
      description: CSR input used when issuing a certificate from a previously generated CSR.
      required:
        - commonName
        - serialNumber
        - der
      properties:
        commonName:
          type: string
          example: "adapter-test.example.com"
        organization:
          type: string
        organizationalUnit:
          type: string
        locality:
          type: string
        state:
          type: string
        country:
          type: string
        email:
          type: string
        serialNumber:
          type: integer
          format: int32
        der:
          type: string
          format: byte
          description: DER-encoded CSR, base64-encoded.
          example: "MIIBKDCBzwIBADCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7oAAwCgYIKoZIzj0EAwIDSAAwRQIhAMiJjZ9Z5w8L7V2qO5n3YgO4Q3t4V6qIh3e3c4C5l7vDAiBd9c0r2k1mWm7y6iY9fKq8pC4d2x3v5z6a7b8c9d0e1g=="

    IssueCertificateRequest:
      type: object
      description: Request to issue a certificate directly from issuer and subject key information.
      required:
        - issuerKeyInfo
        - issuer
        - subjectKeyInfo
        - subject
        - serialNumber
      properties:
        issuerKeyInfo:
          $ref: '#/components/schemas/KeyInfo'
        issuer:
          $ref: '#/components/schemas/X509DistinguishedName'
        subjectKeyInfo:
          $ref: '#/components/schemas/ResolvedKeyInfo'
        subject:
          $ref: '#/components/schemas/X509DistinguishedName'
        serialNumber:
          type: integer
          format: int32
          example: 43
        notBefore:
          type: string
          description: Certificate validity start as an ISO local date-time.
          example: "2026-06-12T00:00:00"
        notAfter:
          type: string
          description: Certificate validity end as an ISO local date-time.
          example: "2027-06-12T00:00:00"

    IssueCertificateFromCsrRequest:
      type: object
      description: Request to issue a certificate using a CSR and issuer key.
      required:
        - issuerKeyInfo
        - issuer
        - subjectKeyInfo
        - csr
      properties:
        issuerKeyInfo:
          $ref: '#/components/schemas/KeyInfo'
        issuer:
          $ref: '#/components/schemas/X509DistinguishedName'
        subjectKeyInfo:
          $ref: '#/components/schemas/ResolvedKeyInfo'
        csr:
          $ref: '#/components/schemas/CertificateSigningRequest'
        serialNumber:
          type: integer
          format: int32
          example: 44
        notBefore:
          type: string
          example: "2026-06-12T00:00:00"
        notAfter:
          type: string
          example: "2027-06-12T00:00:00"

    CertificateResponse:
      type: object
      description: Issued certificate and the key information it binds.
      required:
        - certificate
        - keyInfo
      properties:
        certificate:
          type: string
          format: byte
          description: DER-encoded certificate, base64-encoded on the wire.
        keyInfo:
          $ref: '#/components/schemas/ResolvedKeyInfo'

    StoreCertificateRequest:
      type: object
      description: Request to store a trusted DER certificate under the path alias.
      required:
        - certificate
      properties:
        certificate:
          type: string
          format: byte
          description: DER-encoded certificate, base64-encoded.
          example: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="

    StoreCertificateChainRequest:
      type: object
      description: Request to store a certificate chain under the path alias.
      required:
        - certificates
      properties:
        certificates:
          type: array
          description: Certificate chain ordered from leaf to root. Each item is a DER certificate, base64-encoded.
          items:
            type: string
            format: byte
            example: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="
        keyInfo:
          $ref: '#/components/schemas/ResolvedKeyInfo'

    CertificateBytesResponse:
      type: object
      description: A single DER certificate.
      required:
        - certificate
      properties:
        certificate:
          type: string
          format: byte
          description: DER-encoded certificate, base64-encoded.
          example: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="

    CertificateChainResponse:
      type: object
      description: Certificate chain ordered from leaf to root.
      required:
        - certificates
      properties:
        certificates:
          type: array
          items:
            type: string
            format: byte
            example: "MIIBrTCCAVOgAwIBAgIBKjAKBggqhkjOPQQDAjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wHhcNMjYwNjEyMDAwMDAwWhcNMjcwNjEyMDAwMDAwWjCBiTELMAkGA1UEBhMCTkwxETAPBgNVBAgMCE92ZXJpanNzZWwxETAPBgNVBAcMCEVuc2NoZWRlMRAwDgYDVQQKDAdTcGhlcmVvbjEVMBMGA1UECwwMSWRlbnRpdHkgS0xTMSEwHwYDVQQDDBhhZGFwdGVyLXRlc3QuZXhhbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASH7p4t3S8CwqTq6m3VZ1B4Kq+zqC5VJxJXx8Yo+9H6c2S6rX8J2Vz5v7s6pBzQz6T1+fQF7rF1Y8fWf+Yc7MAoGCCqGSM49BAMCA0cAMEQCIGC4wURyX5Tq5G1mdxNhGxVh8wK72L6X8RhgG55zV1i5AiA3CN8Z+M+Hh+z4RO+f5YqZlE7CqLjO3iHcEJdU2r6eHg=="

    CertificateAliasesResponse:
      type: object
      description: Alias names stored in a certificate or certificate-chain store.
      required:
        - aliases
      properties:
        aliases:
          type: array
          items:
            type: string
            example: "issuer-chain"

    GenerateKey:
      type: object
      description: Parameters for key generation.
      properties:
        alias:
          type: string
          description: Alias for the generated key.
          example: "my-alias"
        use:
          $ref: '#/components/schemas/JwkUse'
        keyOperations:
          type: array
          items:
            $ref: '#/components/schemas/KeyOperations'
        alg:
          $ref: '#/components/schemas/SignatureAlgorithm'

    JoseKeyPair:
      $ref: './kms-components.yml#/components/schemas/JoseKeyPair'
    JwkUse:
      $ref: './kms-components.yml#/components/schemas/JwkUse'
    JwkKeyType:
      $ref: './kms-components.yml#/components/schemas/JwkKeyType'
    Jwk:
      $ref: './kms-components.yml#/components/schemas/Jwk'
    CoseKeyType:
      $ref: './kms-components.yml#/components/schemas/CoseKeyType'
    CoseKey:
      $ref: './kms-components.yml#/components/schemas/CoseKey'
    KeyInfo:
      $ref: './kms-components.yml#/components/schemas/KeyInfo'
    ResolvedKeyInfo:
      $ref: './kms-components.yml#/components/schemas/ResolvedKeyInfo'
    ManagedKeyInfo:
      $ref: './kms-components.yml#/components/schemas/ManagedKeyInfo'
    KeyProviderType:
      $ref: './kms-components.yml#/components/schemas/KeyProviderType'
    KeyOperations:
      $ref: './kms-components.yml#/components/schemas/KeyOperations'
    KeyProvider:
      $ref: './kms-components.yml#/components/schemas/KeyProvider'
    KeyProviderResponse:
      description: Response body containing the details of a Key Provider instance.
      type: object
      allOf:
        - $ref: '#/components/schemas/KeyProvider'

    KeyType:
      $ref: './kms-components.yml#/components/schemas/KeyType'
    KeyVisibility:
      $ref: './kms-components.yml#/components/schemas/KeyVisibility'
    KeyEncoding:
      $ref: './kms-components.yml#/components/schemas/KeyEncoding'
    CreateRawSignatureResponse:
      description: Response body containing the created signature.
      type: object
      required:
        - signature
      properties:
        signature:
          type: string
          format: byte
          description: >
            The created signature, base64-encoded. Pass this value back, together with
            the same keyInfo and input, to POST /signatures/raw/verify.
          example: "MEUCIQDx1c0r2k1mWmExampleSignatureBytesBase64EncodedAA"

    GetKeyResponse:
      description: Response body containing a managed key.
      type: object
      required:
        - keyInfo
      properties:
        keyInfo:
          $ref: '#/components/schemas/ManagedKeyInfo'

    GenerateKeyResponse:
      description: Response body containing a generated key pair.
      type: object
      required:
        - keyPair
      properties:
        keyPair:
          $ref: '#/components/schemas/ManagedKeyPair'

    ImportKeyResponse:
      description: Response body containing an imported key.
      type: object
      required:
        - keyInfo
      properties:
        keyInfo:
          $ref: '#/components/schemas/ManagedKeyInfo'

    RegisterKeyReferenceRequest:
      description: Request body for registering an existing provider key for platform use.
      type: object
      required:
        - providerId
        - alias
      properties:
        providerId:
          type: string
          description: The provider that holds the key.
          example: "4895d0cf-2061-41cb-8fd4-13af5724569e"
        alias:
          type: string
          description: Alias to register the key under.
          example: "my-key-alias"
        kid:
          type: string
          description: Optional kid for the key.
          example: "did:example:123#key-1"

    RegisterKeyReferenceResponse:
      description: Response body for a registered key reference.
      type: object
      required:
        - registered
        - alias
        - providerId
      properties:
        registered:
          type: boolean
          description: Whether the key was successfully registered.
          example: true
        alias:
          type: string
          description: The alias the key was registered under.
          example: "my-key-alias"
        providerId:
          type: string
          description: The provider that holds the key.
          example: "4895d0cf-2061-41cb-8fd4-13af5724569e"
        kid:
          type: string
          description: Optional kid for the key.
          example: "did:example:123#key-1"

    ListResolversResponse:
      description: Response body containing all the resolvers.
      type: object
      required:
        - resolvers
      properties:
        resolvers:
          type: array
          items:
            $ref: '#/components/schemas/Resolver'

    ListKeysResponse:
      description: Response body containing key references (metadata only, no key material).
      type: object
      required:
        - keyInfos
      properties:
        keyInfos:
          type: array
          items:
            $ref: '#/components/schemas/KeyInfo'

    ListKeyProvidersResponse:
      description: Response body containing the details of a Key Provider instance.
      type: object
      required:
        - providers
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/KeyProvider'

    LookupMode:
      $ref: './kms-components.yml#/components/schemas/LookupMode'
    ManagedKeyPair:
      $ref: './kms-components.yml#/components/schemas/ManagedKeyPair'
    MaskGenFunction:
      $ref: './kms-components.yml#/components/schemas/MaskGenFunction'
    Signature:
      $ref: './kms-components.yml#/components/schemas/Signature'
    SignatureAlgorithm:
      $ref: './kms-components.yml#/components/schemas/SignatureAlgorithm'
    SignInput:
      $ref: './kms-components.yml#/components/schemas/SignInput'
    SignOutput:
      $ref: './kms-components.yml#/components/schemas/SignOutput'
    VerifyRawSignatureResponse:
      description: Response body containing the details of the signature verification.
      type: object
      required:
        - isValid
      properties:
        isValid:
          type: boolean
          description: Indicates whether the signature is valid or not.
          example: true

    ImportKey:
      type: object
      description: Request body for importing externally supplied key material.
      required:
        - keyInfo
      properties:
        keyInfo:
          $ref: '#/components/schemas/ResolvedKeyInfo'
        certChain:
          type: array
          items:
            type: string
          description: X.509 certificate chain as base64-encoded DER certificates.

    GenerateKeyGlobal:
      type: object
      description: Parameters for global key generation with optional provider specification.
      allOf:
        - $ref: '#/components/schemas/GenerateKey'
        - type: object
          properties:
            providerId:
              type: string
              description: Optional provider ID. If not specified, the default provider will be used.
              example: "4895d0cf-2061-41cb-8fd4-13af5724569e"

    ResolvePublicKey:
      type: object
      description: Request body for resolving a public key.
      required:
        - keyInfo
      properties:
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        identifierMethod:
          $ref: '#/components/schemas/IdentifierMethod'
        trustedCerts:
          type: array
          items:
            type: string
          description: Optional array of trusted certificates (base64-encoded) that may be used in the resolution process.
        verifyX509CertificateChain:
          type: boolean
          description: Optional boolean indicating whether the X.509 certificate chain should be verified.
          default: false

    UpdateKeyProvider:
      description: Request body for updating an existing Key Provider instance.
      type: object
      properties:
        azureKeyvaultSettings:
          $ref: '#/components/schemas/AzureKeyVaultSetting'
        awsKmsSettings:
          $ref: '#/components/schemas/AwsKmsSetting'
        cacheEnabled:
          type: boolean
          description: Whether to enable caching for keys retrieved from this provider.
        cacheTTLInSeconds:
          type: integer
          format: int32
          description: Time-to-live for cached keys in seconds (if cacheEnabled is true).
          minimum: 0

    VerifyRawSignature:
      description: Request body for verifying a raw signature.
      type: object
      required:
        - keyInfo
        - input
        - signature
      properties:
        keyInfo:
          $ref: '#/components/schemas/KeyInfo'
        input:
          type: string
          format: byte
          description: The original bytes that were signed, base64-encoded. The example is the string "hello".
          example: "aGVsbG8="
        signature:
          type: string
          format: byte
          description: The signature to verify, base64-encoded (as returned by POST /signatures/raw/create).
          example: "MEUCIQDx1c0r2k1mWmExampleSignatureBytesBase64EncodedAA"

    VerifySimpleSignature:
      description: Request body for verifying a digital signature.
      type: object
      required:
        - signInput
        - signature
      properties:
        signInput:
          $ref: '#/components/schemas/SignInput'
        signature:
          $ref: '#/components/schemas/Signature'

    Resolver:
      $ref: './kms-components.yml#/components/schemas/Resolver'
    KeyResolver:
      $ref: './kms-components.yml#/components/schemas/KeyResolver'
    IdentifierMethod:
      $ref: './kms-components.yml#/components/schemas/IdentifierMethod'