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

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.

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.
GET	/certificates	List trusted certificate aliases. Accepts optional providerId.
GET / POST / DELETE	/certificates/{alias}	Read, store, or delete a trusted certificate. Accepts optional providerId.
GET	/certificate-chains	List certificate-chain aliases. Accepts optional providerId.
GET / POST / DELETE	/certificate-chains/{alias}	Read, store, or delete a certificate chain. Accepts optional providerId.

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