Hanzo KMS Java SDK

If you're working with Java, the official Hanzo KMS Java SDK package is the easiest way to fetch and work with secrets for your application.

Installation

Replace {version} with the version of the SDK you wish to use. This documentation covers version >=3.0.0.

Maven

<dependency>
    <groupId>com.kms</groupId>
    <artifactId>sdk</artifactId>
    <version>{version}</version>
</dependency>

Gradle

  implementation group: 'com.kms', name: 'sdk', version: '{version}'

Others

For other build tools, please check our package snippets, and select the build tool you're using for your project.

Getting Started

package com.example.example;


public class Example {

  public static void main(String[] args) {
    var sdk = new Hanzo KMSSdk(
      new SdkConfig.Builder()
        // Optional, will default to https://app.kms.hanzo.ai
        .withSiteUrl("https://your-kms-instance.com")
        .build()
    );

    sdk.Auth().UniversalAuthLogin(
      "CLIENT_ID",
      "CLIENT_SECRET"
    );

    var secret = sdk.Secrets().GetSecret(
      "<secret-name>",
      "<project-id>",
      "<env-slug>",
      "<secret-path>",
      null, // Expand Secret References (boolean, optional)
      null, // Include Imports (boolean, optional)
      null  // Secret Type (shared/personal, defaults to shared, optional)
      );


    System.out.println(secret);
  }
}

Core Methods

The SDK methods are organized into the following high-level categories:

Auth(): Handles authentication methods.

Secrets(): Manages CRUD operations for secrets.

`Auth`

The Auth component provides methods for authentication:

Universal Auth

Authenticating

public void UniversalAuthLogin(
  String clientId,
  String clientSecret
)
throws Hanzo KMSException

sdk.Auth().UniversalAuthLogin(
  "CLIENT_ID",
  "CLIENT_SECRET"
);

Parameters:

clientId (string): The client ID of your Machine Identity.

clientSecret (string): The client secret of your Machine Identity.

Revoking

// No-arg: revokes the current session token stored in the SDK
public void RevokeToken()
throws Hanzo KMSException

// Explicit: revokes a specific access token
public void RevokeToken(
  String accessToken
)
throws Hanzo KMSException

The recommended approach is to call RevokeToken() without arguments, which revokes the token currently stored in the SDK session:

sdk.Auth().RevokeToken();

Alternatively, you can pass an explicit access token to revoke:

sdk.Auth().RevokeToken("ACCESS_TOKEN");

Parameters (explicit variant):

accessToken (String): The access token to revoke.

AWS Auth

public void AwsAuthLogin(
  String identityId
)
throws Hanzo KMSException

sdk.Auth().AwsAuthLogin("<machine-identity-id>");

Parameters:

identityId (String): The ID of the machine identity to authenticate with.

LDAP Auth

public void LdapAuthLogin(
  LdapAuthLoginInput input
)
throws Hanzo KMSException

var input = LdapAuthLoginInput
  .builder()
  .identityId("<machine-identity-id>")
  .username("<ldap-username>")
  .password("<ldap-password>")
  .build();

sdk.Auth().LdapAuthLogin(input);

Parameters:

input (LdapAuthLoginInput): The input for authenticating with LDAP.

identityId (String): The ID of the machine identity to authenticate with.
username (String): The LDAP username.
password (String): The LDAP password.

Access Token Auth

Authenticating

public void SetAccessToken(
  String accessToken
)
throws Hanzo KMSException

sdk.Auth().SetAccessToken("ACCESS_TOKEN");

Parameters:

accessToken (string): The access token you want to use for authentication.

`Secrets`

This sub-class handles operations related to secrets:

List Secrets

public List<Secret> ListSecrets(
    String projectId,
    String environmentSlug,
    String secretPath,
    Boolean expandSecretReferences,
    Boolean recursive,
    Boolean includeImports,
    Boolean setSecretsOnSystemProperties
)

throws Hanzo KMSException

List<Secret> secrets = sdk.Secrets().ListSecrets(
  "<project-id>",
  "<env-slug>", // dev, prod, staging, etc.
  "/secret/path", // `/` is the root folder
  false, // Should expand secret references
  false, // Should get secrets recursively from sub folders
  false, // Should include imports
  false // Should set the fetched secrets as key/value pairs on the system properties. Makes the secrets accessible as System.getProperty("<secret-key>")
);

Parameters:

projectId (string): The ID of your project.

environmentSlug (string): The environment in which to list secrets (e.g., "dev").

secretPath (string): The path to the secrets.

expandSecretReferences (boolean): Whether to expand secret references.

recursive (boolean): Whether to list secrets recursively.

includeImports (boolean): Whether to include imported secrets.

setSecretsOnSystemProperties (boolean): Set the retrieved secrets as key/value pairs on the system properties, making them accessible through System.getProperty("<secret-key>")

Returns:

List<Secret>: The response containing the list of secrets.

Create Secret

public Secret CreateSecret(
    String secretName,
    String secretValue,
    String projectId,
    String environmentSlug,
    String secretPath
)
throws Hanzo KMSException

Secret newSecret = sdk.Secrets().CreateSecret(
  "NEW_SECRET_NAME",
  "secret-value",
  "<project-id>",
  "<env-slug>", // dev, prod, staging, etc.
  "/secret/path", // `/` is the root folder
);

Parameters:

secretName (string): The name of the secret to create

secretValue (string): The value of the secret.

projectId (string): The ID of your project.

environmentSlug (string): The environment in which to create the secret.

secretPath (string, optional): The path to the secret.

Returns:

Secret: The created secret.

Update Secret

public Secret UpdateSecret(
    String secretName,
    String projectId,
    String environmentSlug,
    String secretPath,
    String newSecretValue,
    String newSecretName
  )
    
throws Hanzo KMSException

Secret updatedSecret = sdk.Secrets().UpdateSecret(
  "SECRET_NAME",
  "<project-id>",
  "<env-slug>", // dev, prod, staging, etc.
  "/secret/path", // `/` is the root folder
  "NEW_SECRET_VALUE", // nullable
  "NEW_SECRET_NAME" // nullable
);

Parameters:

secretName (string): The name of the secret to update.

projectId (string): The ID of your project.

environmentSlug (string): The environment in which to update the secret.

secretPath (string): The path to the secret.

newSecretValue (string, nullable): The new value of the secret.

newSecretName (string, nullable): A new name for the secret.

Returns:

Secret: The updated secret.

Get Secret by Name

public Secret GetSecret(
    String secretName,
    String projectId,
    String environmentSlug,
    String secretPath,
    Boolean expandSecretReferences,
    Boolean includeImports,
    String secretType
  )
throws Hanzo KMSException

Secret secret = sdk.Secrets().GetSecret(
  "SECRET_NAME",
  "<project-id>",
  "<env-slug>", // dev, prod, staging, etc.
  "/secret/path", // `/` is the root folder
  false, // Should expand secret references
  false, // Should get secrets recursively from sub folders
  false, // Should include imports
  "shared" // Optional Secret Type (defaults to "shared")
);

Parameters:

secretName (string): The name of the secret to get`

projectId (string): The ID of your project.

environmentSlug (string): The environment in which to retrieve the secret.

secretPath (string): The path to the secret.

expandSecretReferences (boolean, optional): Whether to expand secret references.

includeImports (boolean, optional): Whether to include imported secrets.

secretType (personal | shared, optional): The type of secret to fetch.

Returns:

Secret: The fetched secret.

Delete Secret by Name

public Secret DeleteSecret(
    String secretName,
    String projectId,
    String environmentSlug,
    String secretPath
  )
throws Hanzo KMSException

Secret deletedSecret = sdk.Secrets().DeleteSecret(
  "SECRET_NAME", 
  "<project-id>",
  "<env-slug>", // dev, prod, staging, etc.
  "/secret/path", // `/` is the root folder
);

Parameters:

secretName (string): The name of the secret to delete.

projectId (string): The ID of your project.

environmentSlug (string): The environment in which to delete the secret.

secretPath (string, optional): The path to the secret.

Returns:

Secret: The deleted secret.

`Folders`

Get Folder By Name

public Folder Get(
  String folderId
);
throws Hanzo KMSException

Folder folder = sdk.Folders().Get("<folder-id>");

Parameters:

folderId (String): The ID of the folder to retrieve.

Returns:

Folder: The retrieved folder.

List Folders

public List<Folder> List(
  ListFoldersInput input
)
throws Hanzo KMSException

ListFoldersInput input = ListFoldersInput
  .builder()
  .projectId("<your-project-id>")
  .environmentSlug("<env-slug>")
  .folderPath("/")
  .recursive(false)
  .build();

List<Folder> folders = sdk.Folders().List(input);

Parameters:

input (ListFoldersInput): The input for listing folders.

projectId (String): The ID of the project to list folders from.
environmentSlug (String): The slug of the environment to list folders from.
folderPath (String): The path to list folders from. Defaults to /.
recursive (Boolean): Whether or not to list sub-folders recursively from the specified folder path and downwards. Defaults to false.

Returns:

List<Folder>: The retrieved folders.

Create Folder

public Folder Create(
  CreateFolderInput input
)
throws Hanzo KMSException

var input = CreateFolderInput
  .builder()
  .projectId("<your-project-id>")
  .environmentSlug("<env-slug>")
  .folderName("<folder-name>")
  .folderPath("/")
  .description("Optional folder description")
  .build();

Folder createdFolder = sdk.Folders().Create(input);

Parameters:

input (CreateFolderInput): The input for creating a folder.

projectId (String): The ID of the project to create the folder in.
environmentSlug (String): The slug of the environment to create the folder in.
folderPath (String): The path to create the folder in. Defaults to /.
folderName (String): The name of the folder to create.
description (String): The description of the folder to create. This is optional.

Returns:

Folder: The created folder.

Update Folder

public Folder Update(
  UpdateFolderInput input
)
throws Hanzo KMSException

var input = UpdateFolderInput
  .builder()
  .projectId("<your-project-id>")
  .environmentSlug("<env-slug>")
  .folderId("<id-of-folder-to-update>")
  .newFolderName("<the-new-folder-name>")
  .folderPath("/")
  .build();

Folder updatedFolder = sdk.Folders().Update(input);

Parameters:

input (UpdateFolderInput): The input for updating a folder.

projectId (String): The ID of the project where the folder exists.
environmentSlug (String): The slug of the environment where the folder exists.
folderPath (String): The path of the folder to update.
folderId (String): The ID of the folder to update.
newFolderName (String): The new folder name.

Returns:

Folder: The updated folder.

Delete Folder

public Folder Delete(
  DeleteFolderInput input
)
throws Hanzo KMSException

var input = DeleteFolderInput
  .builder()
  .folderId("<the-folder-id>")
  .environmentSlug("<env-slug>")
  .projectId("<your-project-id>")
  .build();

Folder deletedFolder = sdk.Folders().Delete(input);

Parameters:

input (DeleteFolderInput): The input for deleting a folder.

projectId (String): The ID of the project where the folder exists.
environmentSlug (String): The slug of the environment where the folder exists.
folderId (String): The ID of the folder to delete.

Returns:

Folder: The deleted folder.

On this page