KMS REST API

The KMS REST API service exposes the KeyManagerService over HTTP, turning every key management operation into a REST call. This is the service to use when mobile or browser clients need to delegate key operations to a server, for example when signing with a hardware-backed key that lives in AWS KMS or Azure Key Vault, or when a backend service needs a centralized key management layer. Requests are evaluated in the authenticated tenant scope.

Under the hood, the service routes each request to the appropriate KMS provider. If your server has multiple providers registered (software, AWS, Azure, mobile), the REST API respects the same provider-selection logic as the local KeyManagerService: explicit provider ID, algorithm-based lookup, or default provider fallback.

Key Endpoints

Keys (/keys)

Method	Path	Description
POST	/keys	Generate a new key pair. Accepts the signature algorithm, optional provider ID, and an alias. Returns the generated key metadata including the key ID and public key.
POST	/keys/import	Import externally supplied key material into the selected provider.
POST	/keys/register	Register an existing provider-side key reference without importing key material.
GET	/keys	List all keys visible to the current session. Supports optional filtering by provider or algorithm.
GET	/keys/{keyId}	Retrieve metadata and the public key for a specific key by its ID.
DELETE	/keys/{keyId}	Delete a key according to its lifecycle mode. An externally managed key removes only the tenant-local EDK reference. A platform-managed key retains the provider deletion behavior.

Provider-scoped key routes mirror the global flow: POST /providers/{providerId}/keys generates a key in that provider, and POST /providers/{providerId}/keys/import imports externally supplied key material into that provider.

POST /keys/register registers an existing key by provider alias and optional immutable kid. The provider must already be configured, active, and authorized for the tenant. Registration verifies the provider identity and creates no key, imports no key material, and creates no certificate-management record. The external reference remains usable through the provider, but DELETE removes only the local reference and leaves the provider key untouched. Repeated deletion remains local-only because the persisted reference retains its lifecycle mode.

Signatures (/signatures)

Method	Path	Description
POST	/signatures	Create a signature. Accepts the key ID, the data to sign (base64-encoded), and the signature algorithm. Returns the signature bytes.
POST	/signatures/verify	Verify a signature. Accepts the key ID (or public key), the original data, the signature, and the algorithm. Returns a boolean result.

Providers (/providers)

Method	Path	Description
GET	/providers	List all registered KMS providers and their capabilities (supported algorithms, hardware backing, etc.).
GET	/capabilities	List capability reports for all providers. Use includeDisabled=true to include disabled providers.
GET	/providers/{providerId}/capabilities	Get the capability report for one provider.
POST	/providers/query	Find all providers matching an operation, algorithm, storage, hardware, or identifier-method requirement.
POST	/providers/query/best	Find the best provider match for a capability query.

Encryption (/encryption)

Method	Path	Description
POST	/encryption/encrypt	Encrypt bytes with a KMS-managed key. Binary JSON fields are base64-encoded.
POST	/encryption/decrypt	Decrypt bytes with a KMS-managed key.
POST	/encryption/wrap	Wrap key material with a KMS-managed wrapping key.
POST	/encryption/unwrap	Unwrap key material with a KMS-managed unwrapping key.
POST	/encryption/key-agreement	Perform key agreement and return the shared secret.

Certificates (/certificates, /certificate-chains)

Method	Path	Description
POST	/certificates/csr	Generate a certificate signing request.
POST	/certificates/issue	Issue a certificate from issuer and subject key information.
POST	/certificates/issue-from-csr	Issue a certificate from a CSR.
POST	/certificates/register	Register an existing provider-native certificate or stored public DER material without taking provider lifecycle ownership.
GET	/certificates	List trusted certificate references owned by the current tenant. Accepts optional providerId.
GET / POST / DELETE	/certificates/{alias}	Read, store, or delete a trusted certificate. Accepts optional providerId.
GET	/certificate-chains	List certificate-chain references owned by the current tenant. Accepts optional providerId.
GET / POST / DELETE	/certificate-chains/{alias}	Read, store, or delete a certificate chain. Accepts optional providerId.

POST /certificate-chains/{alias} stores a leaf-to-root certificate chain for the existing certificate-store behavior. For an existing alias, omit keyInfo; a public-only keyInfo may also be supplied as metadata. Do not send the private JWK member d.

The additive registration contract distinguishes PROVIDER_NATIVE from STORED_PUBLIC_MATERIAL. A provider-native registration reads a supported certificate through the tenant-authorized provider, resolves the linked key through the same boundary, and verifies that the leaf public key matches. A stored-material registration validates and stores the public DER chain, then performs the same key binding. Both forms keep private key material in the provider.

Azure Key Vault supports provider-native leaf reads only. The service does not follow certificate AIA URLs, export a PFX, or synthesize a chain. AWS KMS has no certificate object API. AWS Certificate Manager and AWS Private CA are separate services, so a certificate chain linked to an AWS KMS key uses STORED_PUBLIC_MATERIAL with public DER unless a separate certificate-capable provider is configured.

Externally managed certificate DELETE removes only the tenant-local reference and never deletes the provider certificate. Repeated requests remain local-only. Platform-managed certificate deletion retains the existing provider deletion behavior. Certificate lists never widen to unfiltered shared-provider enumeration.

A provider-supplied x5c, x5t, or x5t#S256 value remains public key and JWKS metadata. It does not create a certificate-management record. A DID verification-method JWK omits the backend provider kid while retaining these public certificate members.

Resolvers (/resolvers)

Method	Path	Description
POST	/resolvers	Resolve an identifier (DID, key alias, JWK thumbprint) to its key material. Useful for looking up keys by external reference.

Including in Your Server

Add the KMS REST server module to your dependencies:

build.gradle.kts

dependencies {
    implementation("com.sphereon.idk:services-kms-rest:0.25.0")
}

The service auto-registers its adapter with the DI graph. Once the module is on the classpath and the KotlinInjectPlugin is installed, calling installUniversalHttpAdapters() mounts the KMS endpoints automatically.

Configuration

The KMS REST API inherits its behavior from the underlying KeyManagerService configuration. The key configuration points are:

• KMS providers: Register the providers you need (software, AWS, Azure, mobile) through the DI graph. See KMS Providers for setup details.
• Default provider: Set which provider handles requests that do not specify a providerId.
• Access control: The service runs within the IDK's tenant and principal scoping, so keys are isolated per tenant/principal by default. Use the KotlinInjectPlugin's tenant and principal resolvers to control who can access which keys.

See Key Management for the full KeyManagerService API reference.

Docker

Each service ships with a Dockerfile and docker-compose configuration in its container/ directory.

Building the image

# Build the fat JAR first
./gradlew :services-kms-rest:buildFatJar

# Build the Docker image
docker compose -f services/kms/container/docker-compose.yaml build

Running with Docker Compose

docker compose -f services/kms/container/docker-compose.yaml up

The service starts on port 8080. Configuration is loaded from container/config/ inside the image. Override settings via environment variables in a .env file next to the docker-compose.yaml.

Image details

Property	Value
Base image	eclipse-temurin:21-jre
Docker image	sphereon/idk-kms-rest:latest
Exposed port	8080
Config location	/app/config/

Next Steps

• Services Overview for an introduction to all available IDK services and the CommandBackedHttpAdapter pattern
• Key Management Guide for the full KeyManagerService API reference
• KMS Providers for configuring software, AWS, Azure, and mobile key providers
• Ktor Integration for details on installing and configuring the KotlinInjectPlugin