Create keys

Creates a NEW API key and returns its secret ONCE.

POST /v1/account/keys

Account → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/account/keys`
Method	`POST`
Operation	`post_account_keys`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Creates a NEW API key and returns its secret ONCE. It never revokes or changes any other key: every key the caller already holds keeps working. The key is filed in the org the caller acts in and names them as its creator.

An org holds at most 1,000 live keys; past that the create is refused until one is revoked.

Request

8 fields, body application/json (required).

Field	In	Type	Required	Description
`budget`	body	account.keyBudget	—
`budget.month`	body	integer (int64)	—	Month is per calendar month, UTC.
`budget.total`	body	integer (int64)	—	Total is over the key's whole life.
`expires`	body	string	—	Expires is when the key stops working, RFC 3339.
`limit`	body	string[]	—	Limit narrows what the key may reach, as `kind:name` entries: `model:zen5`, `project:acme`, `product:commerce`, or `model:*` for a whole kind.
`name`	body	string	—	Name labels the key.
`rate`	body	integer (int64)	—	Rate caps the key's requests a minute; past it a request is refused 429.
`type`	body	string	—	Type is the key class: "secret" (sk-, session-equivalent, belongs on a server) or "publishable" (pk-, org-identifying, safe in a browser bundle).

Response

Status	Body	Meaning
`200`	account.apiKey	ok
`default`	problem-details	refused

200 body — 20 fields.

Field	In	Type	Always	Description
`budget`	body	account.keyBudget	—
`budget.month`	body	integer (int64)	—	Month is per calendar month, UTC.
`budget.total`	body	integer (int64)	—	Total is over the key's whole life.
`created`	body	string	—	Created is when the key was minted (RFC 3339).
`creator`	body	string	—	Creator is the person the key speaks for, `<org>/<user>`: who created it.
`expires`	body	string	—	Expires is when the key stops working (RFC 3339).
`id`	body	string	—	ID addresses this key in PATCH and DELETE /v1/account/keys/{id}.
`key`	body	string	—	Key is the full credential.
`limit`	body	string[]	—	Limit is what this key may reach, as `kind:name` entries — `model:zen5`, `project:acme`, `product:train` (read and write), `read:billing` (read only), `read:*` (a read-only key).
`name`	body	string	—	Name is the key's label, chosen by the person who made it.
`prefix`	body	string	—	Prefix is the head of the credential this key's holder presents — the sk- of a secret key — enough to tell which string a row is, never enough to use.
`rate`	body	integer (int64)	—	Rate is how many requests a minute the key may make.
`revoked`	body	string	—
`revoker`	body	string	—	Revoker is who revoked the key, `<org>/<user>`, and Revoked when.
`spend`	body	account.keyBudget	—
`spend.month`	body	integer (int64)	—	Month is per calendar month, UTC.
`spend.total`	body	integer (int64)	—	Total is over the key's whole life.
`status`	body	string	—	Status is active, expired, revoked, or disabled (switched off in IAM).
`type`	body	string	—	Type is the key class: secret (sk-) or publishable (pk-).
`used`	body	string	—	Used is when the key was last used (RFC 3339).

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo account keys create

.ts

.py

.go

.rs

.java

import { Configuration, AccountApi } from 'hanzoai';

const api = new AccountApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postAccountKeys({ budget: {"month":0,"total":0}, expires: "<expires>" });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AccountApi(client).post_account_keys(budget={"month":0,"total":0}, expires="<expires>")

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

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

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

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

let result = account_api::post_account_keys(&cfg, Default::default()).await?;

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

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

var result = new AccountApi(client).postAccountKeys();

curl -X POST https://api.hanzo.ai/v1/account/keys \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "budget": {
         "month": 0,
         "total": 0
       },
       "expires": "<expires>"
     }'

MCP reaches account through the account tool, which names its 6 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

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_account_appearance"
         }
       }
     }'

Account API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate avatar NextCreate orgs