HashiCorp Vault

Vault is one server doing four jobs: holding static secrets, minting dynamic ones, encrypting on demand, and deciding whether a token may act. Those come apart here — /v1/kms (5 operations) is custody, /v1/iam (159) is identity and credentials, /v1/authz (3) is the decision, and /v1/provisioning (28) is the backend a dynamic credential used to point at. The difference that costs the most to port is the mount: in Vault a path is at once where a secret lives, which engine serves it, and what a policy matches, so secret/data/backend/prd has to be spelled the same way in the write, in the policy, and in the role bound to that policy. Here path and env are storage coordinates and nothing else — authority is org membership, and the org is derived from the key rather than named in the request.

Start here

Mint a key, seal one secret, list what is held — three calls, no mount and no policy.

# 1. mint a key — sk- belongs on a server, pk- is safe in a browser
curl -sS -X POST https://api.hanzo.ai/v1/account/keys \
  -H "Authorization: Bearer $HANZO_SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"type":"secret"}'

# 2. seal one secret — env is required on a write and has no default
curl -sS -X POST https://api.hanzo.ai/v1/kms/secrets \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"path":"backend","env":"prd","name":"SIGNING_SECRET","value":"s3cr3t"}'

# 3. see what your org holds
curl -sS "https://api.hanzo.ai/v1/kms/secrets?path=backend&env=prd" \
  -H "Authorization: Bearer $HANZO_API_KEY"

The write sealed the value under a fresh per-secret data key wrapped by the master key; the listing came back with name, path, environment and sealing scheme, and no value. Neither call named an org — the store root comes from the validated key — so there is no namespace, mount name or policy path to spell twice and get out of step.

Core capabilities

Nouns

Secrets

Identity, policy and tokens

The engines

The call

Vault, giving CI read access to one production secret:

# 1. the policy
curl -sS -X PUT "$VAULT_ADDR/v1/sys/policies/acl/ci-read" \
  -H "X-Vault-Token: $VAULT_TOKEN" -H "X-Vault-Namespace: acme" \
  -d '{"policy":"path \"secret/data/backend/prd\" { capabilities = [\"read\"] }"}'

# 2. a role bound to it
curl -sS -X POST "$VAULT_ADDR/v1/auth/approle/role/ci" \
  -H "X-Vault-Token: $VAULT_TOKEN" -H "X-Vault-Namespace: acme" \
  -d '{"token_policies":"ci-read","token_ttl":"1h"}'

# 3 and 4. the two halves of the credential
curl -sS "$VAULT_ADDR/v1/auth/approle/role/ci/role-id" \
  -H "X-Vault-Token: $VAULT_TOKEN"
curl -sS -X POST "$VAULT_ADDR/v1/auth/approle/role/ci/secret-id" \
  -H "X-Vault-Token: $VAULT_TOKEN"

# 5. exchange them for a client token
curl -sS -X POST "$VAULT_ADDR/v1/auth/approle/login" \
  -d '{"role_id":"'"$ROLE_ID"'","secret_id":"'"$SECRET_ID"'"}'

# 6. read
curl -sS "$VAULT_ADDR/v1/secret/data/backend/prd" \
  -H "X-Vault-Token: $CLIENT_TOKEN" -H "X-Vault-Namespace: acme"

Hanzo, the same thing:

# 1. an identity for the program; the secret half is shown once, here
curl -sS -X POST https://api.hanzo.ai/v1/iam/service-accounts \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"ci"}'

# 2. what it may see
curl -sS "https://api.hanzo.ai/v1/kms/secrets?path=backend&env=prd" \
  -H "Authorization: Bearer $CI_KEY"

The write, side by side:

curl -sS -X POST "$VAULT_ADDR/v1/secret/data/backend/prd" \
  -H "X-Vault-Token: $VAULT_TOKEN" -H "X-Vault-Namespace: acme" \
  -d '{"data":{"SIGNING_SECRET":"s3cr3t"}}'

curl -sS -X POST https://api.hanzo.ai/v1/kms/secrets \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"path":"backend","env":"prd","name":"SIGNING_SECRET","value":"s3cr3t"}'

Six requests to two, and five identifiers that must agree to none. Vault's namespace header, mount name, policy path string, role name and KV path all have to line up, and the one that most often does not is the path: KV v2 puts data/ in the API path and not in the CLI path, so a policy copied from vault kv get secret/backend/prd denies a read of secret/data/backend/prd, and the 403 names the read rather than the policy that refused it.

Nothing here can drift that way, because path never appears in a policy to disagree with itself and the store root is derived from the org claim in the key — a caller has no way to write down another tenant's namespace. Note which credential does which half: the CI key reads, and cannot write, because a machine credential holds no org membership and so is never an org admin.

What does not carry

No transit engine. transit/encrypt and transit/decrypt take your plaintext and hand back ciphertext, so an application never holds a key. Sealing here happens beneath /v1/kms/secrets — a per-secret data key wrapped by the master key — and is not exposed as an operation over bytes you supply. Signing is: POST /v1/wallet/{id}/sign produces a secp256k1 signature over a 32-byte digest, with the private key never leaving KMS or MPC custody. That is a signing service, not a general cipher.

No route returns a secret's value. GET /v1/kms/secrets enumerates what is held and there is no per-secret read beside it. vault kv get ports to a listing; vault agent template rendering and consul-template do not, because both exist to pull values into a file on disk.

No leases, so nothing to renew. Every dynamic thing in Vault carries a lease, a TTL, sys/leases/renew and a max_ttl that eventually forces a re-auth. Keys here are valid until replaced, and replacement is one call: POST /v1/iam/service-accounts/{name}/keys mints the successor and invalidates the prior key in the same operation, so there is no window in which both are live. Revocation is immediate rather than scheduled — a token retired at POST /v1/iam/oauth/revoke reads as dead at POST /v1/iam/oauth/introspect on the next call, where Vault's expiration manager revokes in the background and retries on failure. Response wrapping, which returns a single-use token in place of a payload, goes with the leases.

No dynamic database users. database/creds/{role} makes a fresh Postgres user per request. POST /v1/provisioning/sql gives your org its own PostgreSQL instance in its own namespace, with the admin password returned once at create and otherwise held in KMS. The isolation boundary moves from a short-lived user to a dedicated instance — a smaller blast radius and a different operational habit to run. The one per-job scoped credential that does exist is the upload grant on POST /v1/projects/{slug}/deployments, which is minted on the 202 and cannot be fetched again.

No private CA. Public certificates are issued by ACME and configured at PUT /v1/ingress/tls. What has no counterpart is pki/issue/{role} — a leaf and its private key minted from a CA of yours, for service-to-service mTLS. POST /v1/iam/certs registers a signing certificate's identity, its name being the JWKS kid, and key material never travels through the call: the deployment supplies it under the registered name.

No sys/ to operate. Vault is software you run — init, Shamir shares, an unseal quorum, raft peers, a mount table, audit devices you attach and tune. None of that ports because none of it is yours. GET /v1/kms/health reports whether the store is open and a master key is present, and that is the whole operational surface.