Skip to content

Key Management SDK — Quick Start

SDK Version: 3.4.0
Prerequisites: an administrative workload with its public key registered and its scopes assigned (Prerequisites)

1. Add the dependency

<dependency>
    <groupId>co.ankatech</groupId>
    <artifactId>ankasecure-key-management-sdk</artifactId>
    <version>3.4.0</version>
</dependency>

import co.ankatech.ankasecure.keymanagement.AnkaSecureKeyManagementSdk;
import co.ankatech.ankasecure.keymanagement.AuthenticatedKeyManagementSdk;
import co.ankatech.ankasecure.keymanagement.WorkloadCredential;
import co.ankatech.ankasecure.keymanagement.query.KeyListQuery;
import co.ankatech.keymanagement.client.keymanagement.model.PageAdminKeyResponse;
import java.nio.file.Path;
import java.util.Properties;
import java.util.UUID;

UUID workloadId = UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71");   // from the tenant administrator

Properties props = new Properties();
props.setProperty("kmsdk.scheme", "https");
props.setProperty("kmsdk.host", "api.example.com");
props.setProperty("kmsdk.port", "443");

AnkaSecureKeyManagementSdk factory = new AnkaSecureKeyManagementSdk(props);

try (AuthenticatedKeyManagementSdk sdk = factory.authenticateWorkload(
        WorkloadCredential.privateKeyJwt(workloadId, Path.of("/etc/acme/workload-key.pem")))) {
    System.out.println("tenant " + sdk.tenantId());
    PageAdminKeyResponse keys = sdk.keys().list(KeyListQuery.firstPage().withStatus("active"));
    keys.getContent().forEach(key -> System.out.println(key.getKid() + " " + key.getStatus()));
}

authenticateWorkload reads the deployment's authorization server metadata, signs a private_key_jwt assertion with the workload's key and obtains a DPoP-bound token. The instance acts in the tenant the token names; no method takes a tenant.

3. Create a key and rotate it

import co.ankatech.keymanagement.client.keymanagement.model.OrchestrationKeyRequest;
import co.ankatech.keymanagement.client.keymanagement.model.RotationMaterialSpec;
import co.ankatech.keymanagement.client.keymanagement.model.RotationRequest;

sdk.keys().create(new OrchestrationKeyRequest()
        .kid("payments-signing-key")
        .kty("ML-DSA")
        .algorithm("ML-DSA-65")
        .purpose(OrchestrationKeyRequest.PurposeEnum.SIGN_VERIFY));

sdk.rotation().rotate("payments-signing-key", new RotationRequest()
        .newMaterial(new RotationMaterialSpec().kty("ML-DSA").alg("ML-DSA-87")));

When the tenant's quorum policy gates a rotation, rotate throws QuorumApprovalPendingException carrying the quorum request's receipt, and the rotation happens once people approve it in the Admin Console.

4. Handle refusals

import co.ankatech.ankasecure.keymanagement.exception.KeyManagementSdkException;

try {
    sdk.keys().get("unknown-key");
} catch (KeyManagementSdkException e) {
    System.out.println(e.getHttpStatus() + " " + e.getProblemType());
}

Classify on the problem type, never on the message.

Next steps

Usage Guide — every operation group.
Key Destruction — how a key is destroyed.
Security Best Practices.

Version: 3.4.0
Last updated: 2026-10-26