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.

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.
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. The underlying KMS provider handles the actual removal.

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.).

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