hanzo-api-kms

Secret custody: your org's secrets sealed at rest, plus threshold signing.

Hanzo KMS

Scope: Secret custody: your org's secrets sealed at rest, plus threshold signing. Surface: 7 operations on /v1/kms Lines: ~123 Last Updated: 2026-08-20 Source: https://api.hanzo.ai/v1/openapi.json (x-app: kms) — generated, do not hand-edit

When to Use This Skill

Activate this skill when:

Your code needs a credential and you refuse to put it in a manifest or an env file
Rotating a secret without redeploying whatever reads it
You need a signature from a key the caller is never allowed to hold
Auditing what secrets an org holds without revealing any value
Calling /v1/kms (7 operations)

Authentication

Every operation takes a Hanzo IAM bearer token. hanzo auth token prints the active short-lived access token for the identity you are signed in as; the org is carried in the token's claim, never in a path or a query parameter.

TOKEN=$(hanzo auth token)
curl -sS https://api.hanzo.ai/v1/... -H "Authorization: Bearer $TOKEN"

The document declares one scheme, bearer, at the top level: Authorization: Bearer <token>. X-Authorization and HTTP Basic carrying the token as the password are accepted spellings of the same header; a browser presents the session cookie instead. There is no product-specific key scheme.

Surface

| Family | Operations | Addresses under it | |---|---|---| | /v1/kms | 7 | auth, config, health, secrets |

Operations

`/v1/kms`

| Method | Path | Summary | |---|---|---| | POST | /v1/kms/auth/login | Exchange a machine credential for an IAM bearer token | | GET | /v1/kms/config | Runtime configuration for the KMS console | | GET | /v1/kms/health | Whether this broker can actually serve secrets | | GET | /v1/kms/secrets | List the secrets your org holds, without their values | | POST | /v1/kms/secrets | Store or replace one secret in your org | | DELETE | /v1/kms/secrets/{wildcard1} | Delete one secret from your org | | GET | /v1/kms/secrets/{wildcard1} | Read one secret's value |

Example Calls

TOKEN=$(hanzo auth token)

Store or replace one secret in your org

curl -sS -X POST "https://api.hanzo.ai/v1/kms/secrets" \
  -H "Authorization: Bearer $TOKEN"

Upserts one secret under the caller's own org. The value is sealed before it is written — a fresh per-secret data key, itself wrapped by the master key — so plaintext never reaches disk. The receipt confirms the name and environment that were written and does not echo the value.

env is REQUIRED on a write and has no default, which is the rule most easily got wrong here: reads and deletes still fall back to the default environment for older callers, but a write must not, because the environment is part of the storage key. A silently defaulted write lands in a bucket the readers that resolve project, environment and path never look in, and the stale value keeps being served — so the write…

name is required, path is an optional subpath beneath the org root, and the org is taken from the validated claim rather than the body.

Requires ADMIN authority over the org — a member reads, an admin writes. A machine credential holds no membership and so is never an org admin: it can read the secrets it was issued for and cannot replace one. Fail-closed admission, in order: admin of the org, well-formed org, master key present — 403, 400 and 503, all decided before any record is touched.

Exchange a machine credential for an IAM bearer token

curl -sS -X POST "https://api.hanzo.ai/v1/kms/auth/login" \
  -H "Authorization: Bearer $TOKEN"

Takes a tenant's machine credential — a client id and client secret — and returns an owner-scoped IAM access token with its lifetime, which is the bearer the caller then carries on the org-scoped secret operations.

It is deliberately public and unauthenticated, because it IS the credential exchange and runs before any principal exists. That makes it the one route in this subsystem rate-limited PER SOURCE IP, keyed on the real TCP peer rather than on any caller-supplied header.

The submitted secret is never logged and never echoed, and failures collapse to one clean status with no upstream detail: 401 when the credential does not authenticate, 502 when the identity provider is unreachable, 503 when no issuer is configured. That is on purpose — a richer error would be a validity oracle for guessed credentials.

List the secrets your org holds, without their values

curl -sS "https://api.hanzo.ai/v1/kms/secrets" \
  -H "Authorization: Bearer $TOKEN"

Returns the METADATA of the caller's own secrets: each one's name, path, environment and sealing scheme. No value and no ciphertext is included — this operation exists to enumerate what is held, and reading a value is a separate, per-secret call.

Composition

Everything that takes a third-party credential reads it from here — integrations, notify, settings
iam decides who the caller is; this decides what that caller may unseal
audit records the read; the two together are the evidence trail
platform and functions inject secrets into a deployment by reference, never by value

Related Skills

hanzo-api/wallet.md — Blockchain key custody: create wallets, rotate their keys, and sign with them.
hanzo-api/security.md — Secret scanning for your code: submit sources, get findings, masked never raw.
hanzo-api/sbom.md — What is inside a container image: every component, resolvable by digest or image ref.
hanzo-api/audit.md — Your org's tamper-evident audit trail: every security-relevant event, hash-chained and…
hanzo/hanzo-kms.md — the repo and how it is operated, not the API surface
hanzo-cloud-architecture/SKILL.md — how one binary serves all of this
hanzo-api/INDEX.md — every Hanzo product, by domain

Last Updated: 2026-08-20 Generated from: https://api.hanzo.ai/v1/openapi.json