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

package main

  "fmt"
  "os"
  "context"
  kms "github.com/kms/go-sdk"
)

func main() {

	client := kms.NewHanzo KMSClient(context.Background(), kms.Config{
		SiteUrl: "https://app.kms.hanzo.ai", // Optional, default is https://app.kms.hanzo.ai
    AutoTokenRefresh: true, // Wether or not to let the SDK handle the access token lifecycle. Defaults to true if not specified.
	})

	_, err := client.Auth().UniversalAuthLogin("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")

	if err != nil {
		fmt.Printf("Authentication failed: %v", err)
		os.Exit(1)
	}

	apiKeySecret, err := client.Secrets().Retrieve(kms.RetrieveSecretOptions{
		SecretKey:   "API_KEY",
		Environment: "dev",
		ProjectID:   "YOUR_PROJECT_ID",
		SecretPath:  "/",
	})

	if err != nil {
		fmt.Printf("Error: %v", err)
		os.Exit(1)
	}

	fmt.Printf("API Key Secret: %v", apiKeySecret)

}

This example demonstrates how to use the Hanzo KMS Go SDK in a simple Go application. The application retrieves a secret named API_KEY from the dev environment of the YOUR_PROJECT_ID project.

We do not recommend hardcoding your Machine Identity Tokens. Setting it as an environment variable would be best.

Installation

$ go get github.com/kms/go-sdk

Configuration

Import the SDK and create a client instance.

client := kms.NewHanzo KMSClient(context.Background(), kms.Config{
		SiteUrl: "https://app.kms.hanzo.ai", // Optional, default is https://api.kms.hanzo.ai
	})

Configuration Options

The URL of the Hanzo KMS API..

Optionally set the user agent that will be used for HTTP requests. (Not recommended)

Whether or not to let the SDK handle the access token lifecycle. Defaults to true if not specified.

Whether or not to suppress logs such as warnings from the token refreshing process. Defaults to false if not specified.

Defines how long certain responses should be cached in memory, in seconds. When set to a positive value, responses from specific methods (like secret fetching) will be cached for this duration. Set to 0 to disable caching.

Allows you to pass custom headers to the HTTP requests made by the SDK. Expected format is a map of Header1: Value1, Header2: Value 2.

Automatic token refreshing

The Hanzo KMS Go SDK supports automatic token refreshing. After using one of the auth methods such as Universal Auth, the SDK will automatically renew and re-authenticate when needed. This behavior is enabled by default, but you can opt-out by setting AutoTokenRefresh to false in the client settings.

  client := kms.NewHanzo KMSClient(context.Background(), kms.Config{
    AutoTokenRefresh: false, // <- Disable automatic token refreshing
  })

When using automatic token refreshing it's important to understand how your application uses the Infiiscal client. If you are instantiating new instances of the client often, it's important to cancel the context when the client is no longer needed to avoid the token refreshing process from running indefinitely.

  ctx, cancel := context.WithCancel(context.Background())
  defer cancel() // Cancel the context when the client is no longer needed

  client := kms.NewHanzo KMSClient(ctx, kms.Config{
    AutoTokenRefresh: true,
  })

  // Use the client

This is only necessary if you are creating multiple instances of the client, and those instances are deleted or otherwise removed throughout the application lifecycle. If you are only creating one instance of the client, and it will be used throughout the lifetime of your application, you don't need to worry about this.

Authentication

The SDK supports a variety of authentication methods. The most common authentication method is Universal Auth, which uses a client ID and client secret to authenticate.

Universal Auth

Using environment variables

Call .Auth().UniversalAuthLogin() with empty arguments to use the following environment variables:

INFISICAL_UNIVERSAL_AUTH_CLIENT_ID - Your machine identity client ID.

INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET - Your machine identity client secret.

Using the SDK directly

_, err := client.Auth().UniversalAuthLogin("CLIENT_ID", "CLIENT_SECRET")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

GCP ID Token Auth

Please note that this authentication method will only work if you're running your application on Google Cloud Platform. Please read more about this authentication method.

Using environment variables

Call .Auth().GcpIdTokenAuthLogin() with empty arguments to use the following environment variables:

INFISICAL_GCP_AUTH_IDENTITY_ID - Your Hanzo KMS Machine Identity ID.

Using the SDK directly

_, err := client.Auth().GcpIdTokenAuthLogin("YOUR_MACHINE_IDENTITY_ID")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

GCP IAM Auth

Using environment variables

Call .Auth().GcpIamAuthLogin() with empty arguments to use the following environment variables:

INFISICAL_GCP_IAM_AUTH_IDENTITY_ID - Your Hanzo KMS Machine Identity ID.

INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH - The path to your GCP service account key file.

Using the SDK directly

_, err = client.Auth().GcpIamAuthLogin("MACHINE_IDENTITY_ID", "SERVICE_ACCOUNT_KEY_FILE_PATH")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

AWS IAM Auth

Please note that this authentication method will only work if you're running your application on AWS. Please read more about this authentication method.

Using environment variables

Call .Auth().AwsIamAuthLogin() with empty arguments to use the following environment variables:

INFISICAL_AWS_IAM_AUTH_IDENTITY_ID - Your Hanzo KMS Machine Identity ID.

Using the SDK directly

_, err = client.Auth().AwsIamAuthLogin("MACHINE_IDENTITY_ID")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

Azure Auth

Please note that this authentication method will only work if you're running your application on Azure. Please read more about this authentication method.

Using environment variables

Call .Auth().AzureAuthLogin() with empty arguments to use the following environment variables:

INFISICAL_AZURE_AUTH_IDENTITY_ID - Your Hanzo KMS Machine Identity ID.

Using the SDK directly

_, err = client.Auth().AzureAuthLogin("MACHINE_IDENTITY_ID")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

Kubernetes Auth

Please note that this authentication method will only work if you're running your application on Kubernetes. Please read more about this authentication method.

Using environment variables

Call .Auth().KubernetesAuthLogin() with empty arguments to use the following environment variables:

INFISICAL_KUBERNETES_IDENTITY_ID - Your Hanzo KMS Machine Identity ID.

INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH_ENV_NAME - The environment variable name that contains the path to the service account token. This is optional and will default to /var/run/secrets/kubernetes.io/serviceaccount/token.

Using the SDK directly

// Service account token path will default to /var/run/secrets/kubernetes.io/serviceaccount/token if empty value is passed
_, err = client.Auth().KubernetesAuthLogin("MACHINE_IDENTITY_ID", "SERVICE_ACCOUNT_TOKEN_PATH")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

JWT Auth

Please note that this authentication method requires a valid JWT token from your JWT issuer. Please read more about this authentication method.

Using the SDK

credential, err := client.Auth().JwtAuthLogin("MACHINE_IDENTITY_ID", "JWT_TOKEN")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

LDAP Auth

Please note that this authentication method requires LDAP credentials. Please read more about this authentication method.

Using environment variables

You can set the INFISICAL_LDAP_AUTH_IDENTITY_ID environment variable and pass empty string for the identity ID:

credential, err := client.Auth().LdapAuthLogin("", "LDAP_USERNAME", "LDAP_PASSWORD")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

Using the SDK directly

credential, err := client.Auth().LdapAuthLogin("MACHINE_IDENTITY_ID", "LDAP_USERNAME", "LDAP_PASSWORD")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

OCI Auth

Please note that this authentication method will only work if you're running your application on Oracle Cloud Infrastructure. Please read more about this authentication method.

Using environment variables

You can set the INFISICAL_OCI_AUTH_IDENTITY_ID environment variable and omit the IdentityID field:

credential, err := client.Auth().OciAuthLogin(kms.OciAuthLoginOptions{
  UserID:      "USER_OCID",
  TenancyID:   "TENANCY_OCID",
  Fingerprint: "FINGERPRINT",
  PrivateKey:  "PRIVATE_KEY",
  Region:      "REGION",
})

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

Using the SDK directly

credential, err := client.Auth().OciAuthLogin(kms.OciAuthLoginOptions{
  IdentityID:  "MACHINE_IDENTITY_ID",
  UserID:      "USER_OCID",
  TenancyID:   "TENANCY_OCID",
  Fingerprint: "FINGERPRINT",
  PrivateKey:  "PRIVATE_KEY",
  Region:      "REGION",
  Passphrase:  nil, // Optional: pointer to string if your private key has a passphrase
})

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

OciAuthLoginOptions fields:

IdentityID (string) - Your Hanzo KMS Machine Identity ID. Can be set via INFISICAL_OCI_AUTH_IDENTITY_ID environment variable.

UserID (string) - Your OCI user OCID.

TenancyID (string) - Your OCI tenancy OCID.

Fingerprint (string) - Your OCI API key fingerprint.

PrivateKey (string) - Your OCI private key (PEM format).

Region (string) - Your OCI region (e.g., us-ashburn-1).

Passphrase (*string) - Optional: pointer to passphrase string if your private key is encrypted.

Organization Authentication

All SDK authentication methods support logging into a sub-organization that your machine identity has access to. This is optional and only necessary when attempting to authenticate into a sub-organization using an identity created at the root organization.

Use the .Auth().WithOrganizationSlug("<organization-slug>") method to specify which organization to authenticate against:

_, err := client.Auth().WithOrganizationSlug("ORGANIZATION_SLUG").UniversalAuthLogin("CLIENT_ID", "CLIENT_SECRET")

if err != nil {
  fmt.Println(err)
  os.Exit(1)
}

If no organization slug is provided, the authentication session defaults to the organization where the machine identity was originally created.

Secrets

List Secrets

client.Secrets().List(options)

Retrieve all secrets within the Hanzo KMS project and environment that client is connected to.

secrets, err := client.Secrets().List(kms.ListSecretsOptions{
  ProjectID:          "PROJECT_ID",
  Environment:        "dev",
  SecretPath:         "/foo/bar",
  AttachToProcessEnv: false,
})

Hanzo KMS Go SDK

On this page