API Keys

Every request to the Hanzo platform is authenticated with a bearer token. This page covers the three key types, how to create and use them, and how to keep them safe.

Key Types and Prefixes

Hanzo uses key prefixes so you can identify a credential at a glance and catch accidental misuse.

API Keys (hk-*)

These are your primary credentials. One hk-* key gives access to all Hanzo services for the project it belongs to: AI API, search, storage, tasks, and everything else.

# All Hanzo API calls use the same header format
curl -H "Authorization: Bearer hk-proj-abc123..." https://api.hanzo.ai/v1/models

Secret Keys (sk-*)

Secret keys are org-scoped credentials used for provider-level operations: configuring upstream LLM providers, managing billing integrations, and inter-service communication. They carry elevated privileges and must never leave your backend.

Widget Keys (hz-*)

Widget keys are designed for client-side use. They have restricted scopes -- typically limited to chat completions and embeddings -- so that exposing them in browser code does not compromise your account.

<!-- Safe to embed in frontend code -->
<script>
  const HANZO_KEY = 'hz-widget-abc123...'
</script>

Creating Keys

In the Console

1. Go to console.hanzo.ai
2. Select your project
3. Click API Keys in the sidebar
4. Click Create Key
5. Choose the key type (hk-* API key or hz-* widget key)
6. Optionally set:
   • Name -- descriptive label (e.g. prod-backend, staging-widget)
   • Expiration -- auto-expire after a set duration
   • Budget -- monthly spend limit for LLM usage
   • Rate limit -- requests per minute cap
7. Copy the key immediately -- it will not be shown again

Key issuance, budgets, and revocation are console operations — there is no public key-minting endpoint, by design: a credential that can mint credentials is the one thing you never want reachable over HTTP with a bearer token.

Using Keys

All Hanzo APIs accept keys via the Authorization header with the Bearer scheme:

Authorization: Bearer hk-proj-abc123...

Every service answers on the one host, api.hanzo.ai, under /v1/<service> — the same key works across all of them:

SDK Configuration

All official SDKs accept the API key as a constructor parameter:

# Python
from hanzoai import Hanzo
client = Hanzo(api_key="hk-your-key")

// TypeScript
import Hanzo from '@hanzo/ai'
const client = new Hanzo({ apiKey: 'hk-your-key' })

// Go
import "github.com/hanzoai/go-sdk"
client := hanzo.NewClient(hanzo.WithAPIKey("hk-your-key"))

Each client defaults to https://api.hanzo.ai/v1. A third-party HTTP client written against the chat-completions shape works too — point its base URL there and give it the same key.

Scopes

Project-Level Keys (hk-*, hz-*)

These keys are bound to a single project. They can only access resources within that project. Switching projects requires a different key.

Org-Level Keys (sk-*)

These keys operate across all projects within an organization. They are used for administrative operations: managing projects, configuring providers, and accessing org-wide analytics.

Key Information and Usage

Spend and usage for the calling credential come from the billing and analytics APIs — same host, same key:

# Current balance
curl https://api.hanzo.ai/v1/billing/balance \
  -H "Authorization: Bearer hk-your-key"

# Itemized metered usage
curl https://api.hanzo.ai/v1/billing/usage \
  -H "Authorization: Bearer hk-your-key"

{ "balance": 0, "holds": 0, "available": 0 }

{
  "count": 2000,
  "usage": [
    {
      "amount": 24,
      "createdAt": "2026-07-25T21:59:35Z",
      "metadata": { "model": "zen-image" },
      "transactionId": "use_daff3c10f561635114c7a78e8d0eea5d"
    }
  ]
}

For rolled-up request/token/spend counts across a range, use GET /v1/analytics/overview?range=30d — see Analytics.

Rotation Best Practices

1. Rotate regularly -- Set key expiration at creation time. 90 days is a reasonable default for production keys.
2. Use KMS for production -- Store keys in Hanzo KMS and sync them to your runtime environment via KMSSecret CRDs. Never hardcode keys in source or commit them to git.
3. Create before you revoke -- Generate the replacement key, deploy it, verify it works, then revoke the old one. Zero-downtime rotation.
4. One key per service -- Give each service or environment its own key. This limits blast radius and makes audit logs useful.
5. Set budgets -- Every production key should have a monthly budget. This prevents runaway costs from bugs or abuse.
6. Monitor usage -- Check /v1/billing/usage or the console dashboard regularly. Unusual spend patterns may indicate a leak.

KMS Integration

For production deployments, use Hanzo KMS to manage API keys as secrets:

# KMSSecret CRD -- syncs a secret from Hanzo KMS into K8s
apiVersion: secrets.lux.network/v1alpha1
kind: KMSSecret
metadata:
  name: hanzo-api-key
spec:
  secretStoreRef:
    name: kms-hanzo
  data:
    - secretKey: HANZO_API_KEY
      remoteRef:
        secretPath: /prod/api-keys
        secretKey: primary

Revoking Keys

Revoke a key from the console: Project → API Keys → Revoke. Revocation is immediate — any in-flight request using the key fails with 401 Unauthorized.

Security Rules

• Never commit keys to git. Use environment variables or KMS.
• Never expose hk-* or sk-* keys client-side. Use hz-* widget keys for browser code.
• Always use HTTPS. All Hanzo endpoints enforce TLS. Plain HTTP connections are rejected.
• Set the minimum scope needed. If a service only needs LLM access, do not give it an org-level secret key.