Create secrets

POST /v1/kms/secrets

Stores or replaces one secret in your org.

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 fails loudly instead.

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.

Opens only for SuperAdmin holding an access token, audited, or for a holder a declared WRITE grant covers at this exact path, key and environment. Org admin confers nothing here. Fail-closed admission, in order: a validated member, well-formed org, master key present, well-formed input, then the grant — 401/403, 400, 503, 400 and 403, all decided before any record is touched.

A value this deployment seals on the org's behalf — an MCP server's credential, a wallet's signing key, a delivery provider's token — is written by the app that holds it, through that app's own operation, and is never replaced here for membership or org admin, whatever the grant declaration says about enforcement.

Request

4 fields, body application/json (required).

Response

200 body — 3 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo kms secrets create

import { Configuration, KmsApi } from 'hanzoai';

const api = new KmsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postKmsSecrets({ env: "<env>", name: "<name>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import KmsApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = KmsApi(client).post_kms_secrets(env="<env>", name="<name>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.KmsAPI.PostKmsSecrets(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, kms_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = kms_api::post_kms_secrets(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.KmsApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new KmsApi(client).postKmsSecrets();

curl -X POST https://api.hanzo.ai/v1/kms/secrets \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "env": "<env>",
       "name": "<name>"
     }'

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_kms_config"
         }
       }
     }'

KMS API · All Hanzo APIs · Interactive reference