Skip to main content

Hanzo KMS - Python SDK

Official Python SDK for Hanzo KMS — secret management for your applications.

The server is luxfi/kms; this SDK speaks its canonical /v1/kms surface and nothing else.

Installation

pip install hanzo-kms

Or with uv:

uv add hanzo-kms

Quick Start

A secret is identified by (org, path, name, env). The org scopes both the URL and the JWT; path, name and env identify the value.

from hanzo_kms import ClientSettings, KMSClient

client = KMSClient(ClientSettings(
    org="lux",
    client_id="your-client-id",
    client_secret="your-client-secret",
))

# List the secret names at a path
names = client.list_secrets("providers/lux", env="prod")

# Read one value
mnemonic = client.get_secret("providers/lux", "deploy-mnemonic", env="prod")

# Create or replace — one upsert; KMS holds one value per (path, name, env)
client.put_secret("providers/lux", "deploy-mnemonic", mnemonic, env="prod")

# Delete
client.delete_secret("providers/lux", "deploy-mnemonic", env="prod")

# Load a whole path into os.environ, keyed by secret name
client.inject_env("providers/lux", env="prod")

env defaults to "default".

Async

AsyncKMSClient is the mirror image of KMSClient — same methods, same arguments.

from hanzo_kms import AsyncKMSClient

async with AsyncKMSClient() as client:
    names = await client.list_secrets("providers/lux", env="prod")

Environment Variables

export HANZO_KMS_URL="https://kms.hanzo.ai"   # default
export HANZO_KMS_ORG="hanzo"                  # default
export HANZO_KMS_CLIENT_ID="your-client-id"
export HANZO_KMS_CLIENT_SECRET="your-client-secret"
# ...or a pre-issued IAM bearer token instead of client credentials:
export HANZO_KMS_TOKEN="eyJ..."

Then:

from hanzo_kms import KMSClient

client = KMSClient()  # configures itself from the environment

Authentication

Two ways, because the server has one login route:

Setting Behavior
client_id + client_secret Exchanged at POST /v1/kms/auth/login for a bearer token
access_token A pre-issued IAM bearer token, used as-is

The AWS / Azure / GCP / Kubernetes / SRP methods this SDK used to advertise were Infisical's. luxfi/kms has never served them.

CLI

hanzo-kms list --path providers/lux --env prod
hanzo-kms get providers/lux deploy-mnemonic --env prod
hanzo-kms set providers/lux deploy-mnemonic "word word ..." --env prod
hanzo-kms delete providers/lux deploy-mnemonic --env prod
hanzo-kms export --path providers/lux --env prod --format json

API Reference

KMSClient

Method Description
list_secrets(path="", env="default") Secret names at a path
get_secret(path, name, env="default") The secret's value
put_secret(path, name, value, env="default") Create or replace
delete_secret(path, name, env="default") Delete
inject_env(path="", env="default", overwrite=False) Load a path into os.environ
health() {"service": "kms", "status": "ok"}

Server surface

POST   /v1/kms/auth/login                            {clientId, clientSecret} -> {accessToken, expiresIn}
GET    /v1/kms/orgs/{org}/secrets?path=&env=         -> {"names": [...]}
GET    /v1/kms/orgs/{org}/secrets/{path}/{name}?env= -> {"secret": {"value": "..."}}
POST   /v1/kms/orgs/{org}/secrets                    {path, name, env, value}
DELETE /v1/kms/orgs/{org}/secrets/{path}/{name}?env=
GET    /healthz | /v1/kms/healthz                    -> {"service": "kms", "status": "ok"}

Two things follow from it:

  • The server splits the trailing path at its LAST slash into (path, name). A name may not contain / — this SDK rejects one rather than let a write land under a key the matching read can never find.
  • There is no versioned read. KMS holds exactly one value per (path, name, env), so get_secret(..., version=N) raises VersionUnsupportedError instead of quietly handing back the current value.

Compatibility

License

MIT License - see LICENSE for details.

Metadata

Release files for hanzo-kms 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hanzo-kms 1.1.1
File Size Uploaded Provenance Actions
hanzo_kms-1.1.1.tar.gz 34.7 kB Without provenance Details for hanzo_kms-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hanzo-kms 1.1.1
File Interpreter ABI Platform Actions
hanzo_kms-1.1.1-py3-none-any.whl Python 3 none any Details for hanzo_kms-1.1.1-py3-none-any.whl

Total release size: 48.7 kB

Release files / hanzo_kms-1.1.1.tar.gz

Download URL hanzo_kms-1.1.1.tar.gz
Size 34.7 kB
Tags Source
SHA-256 checksum
How to use checksums
819c51767ef5ecbe55ffb4176c41a4c7f2d724d50151afb868f9378956900c2c
BLAKE2b-256 checksum
How to use checksums
f7b105c95c685803efedf17b62af8fd44d36f317509682e7ee70813b0adcba1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Release files / hanzo_kms-1.1.1-py3-none-any.whl

Download URL hanzo_kms-1.1.1-py3-none-any.whl
Size 14.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ff12fced530d9484d35c8edd4ac4f56688ec2e81fe3572536425b1d9ae6c20b7
BLAKE2b-256 checksum
How to use checksums
dddb908fb3a72e36a55993a88e698eb30eafa6d378e2f570392deff37fc72ca6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.14

Security for hanzo-kms 1.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page