The KMS v2 API (/api/v2/kms/*) is QuantumLock’s signing plane: named keys, signature operations, rotation and revocation, and the KMS-sealed evidence bundles built on top of them. QuantumLock separates policy (which algorithm, when to sign, key lifecycle) from custody (where private keys physically live).

​
Custody providers

Which provider serves a request is decided by the deployment’s crypto policy and trust profile (for example, defense requires a PKCS#11 HSM and refuses everything else; sovereign profiles require cloud KMS or HSM custody). In BYOC setups the customer owns the cloud account and pays the cloud provider directly.
Fail-closed custody. If the declared custody cannot be provided — the HSM is unreachable, the cloud SDK is missing, the key store is down — the request is answered 503 Key custody unavailable and nothing is signed. There is deliberately no silent fallback to software keys: a signature produced by an in-memory key must never be indistinguishable from a hardware-backed one.

​
Authentication ordering

On every KMS and evidence route, authentication and scope checks resolve before the KMS provider is constructed. An unauthenticated or under-scoped caller is answered 401/403 without any provider being built — so anonymous traffic can neither probe the deployment’s custody posture off a 503 nor cause key material to be created as a side effect. This ordering is enforced by a regression test in the service.

​
Signing

POST /api/v2/kms/sign — requires the quantumlock:sign scope. You sign a digest (base64), not the raw document:
Key references are tenant-namespaced: your release-signing cannot collide with, read, or sign for another tenant’s key of the same name.

​
Hybrid signing (classical + post-quantum)

POST /api/v2/kms/sign/hybrid produces two signatures over the same digest — one from a classical key, one from a post-quantum (ML-DSA) key:
Hybrid verification requires both signatures to check out — a break of either single algorithm does not break the pair. This is the same defense-in-depth construction used for evidence bundle sealing.

​
Verification

POST /api/v2/kms/verify — requires only quantumlock:read:
historical / signature_id let you verify signatures made under a key version that has since been rotated or revoked: revocation refuses a key for new work but preserves the ability to check what it already signed.

​
Key lifecycle

Every lifecycle operation is recorded in the audit trail with the acting principal; if the operation cannot be durably recorded, it is refused rather than performed unrecorded. For richer lifecycle states (suspend, expire, archive, destroy, wrap) and policy-controlled entropy, use the Enterprise Key Engine.

​
KMS-sealed evidence

The /api/v2/evidence/bundle* routes create and verify evidence bundles sealed by KMS keys, including hybrid sealing via use_hybrid with classical_key_ref + pqc_key_ref. See Evidence & Transparency.

​
Operator: configuration and readiness

/api/v2/kms/config/* reports and tests the deployment’s custody posture — current provider, where keys physically live, whether the PQC library is loaded, and a production-readiness verdict whose checks fail closed (a check that cannot be evaluated counts as failed, never passed). These routes are for operators and platform administration, not application traffic.