Connections

A connection lets your org use its own provider account through Hanzo. Paste an API key or sign in, and two things follow: Hanzo can serve that provider's models billed to your account, and that provider's spend appears beside your Hanzo spend in one usage view.

This is per-org bring-your-own credentials. It is separate from the shared gateway upstreams that back the model catalogue — those need no setup from you.

Connect with an API key

curl -X POST https://api.hanzo.ai/v1/ai/connections \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "openai", "apiKey": "sk-..." }'

{ "provider": "openai", "connected": true, "account_label": "acme/openai" }

The org comes from your verified identity — never from a field in the body — so a connection can only ever land in your own org. The response carries a label, never the key.

The console offers OpenAI (sk-…), Anthropic (sk-ant-…), and Google Gemini (AIza…). The API additionally accepts openrouter, deepseek, groq, mistral, together, fireworks, xai, cohere, and huggingface.

Connect by signing in

For providers whose OAuth app this deployment has provisioned, start the flow instead of pasting a key:

curl "https://api.hanzo.ai/v1/ai/connections/anthropic/authorize?format=json" \
  -H "Authorization: Bearer $HANZO_API_KEY"

Returns { "authorizeUrl": "..." } to send the user to; a provider whose OAuth app is not configured here answers 503. The callback recovers your org from a signed state parameter rather than from a header, so a callback cannot be redirected into another tenant.

Where the credential lives

The key is sealed into Hanzo KMS before the connection row is written, and only a kms:// reference is stored beside it. If KMS is not reachable the connection is refused outright — the code has no path that stores a provider key in the clear. The secret name is scoped per org and per provider.

Disconnecting disables the connection and tombstones the secret:

curl -X DELETE https://api.hanzo.ai/v1/ai/connections/openai \
  -H "Authorization: Bearer $HANZO_API_KEY"

Imported spend

GET /v1/ai/connections/{provider}/usage unseals the key server-side, calls the provider's own usage API, and returns a normalized shape:

{
  "provider": "openai",
  "connected": true,
  "available": true,
  "currency": "USD",
  "start": "...", "end": "...", "interval": "day",
  "totals": { "spendCents": 41230, "tokens": 8100422, "inputTokens": 0, "outputTokens": 0, "requests": 9134 },
  "series": [{ "t": "...", "spendCents": 0, "tokens": 0, "requests": 0 }],
  "byModel": [{ "model": "gpt-4o-mini" }]
}

Import is implemented for OpenAI, Anthropic, and OpenRouter. The rest connect and serve, but report available: false with a note rather than a number — absence is stated, never filled in. OpenAI's org usage endpoints need an admin-scoped key; a key without that scope also comes back as a note.

List what is connected

curl https://api.hanzo.ai/v1/ai/connections \
  -H "Authorization: Bearer $HANZO_API_KEY"

Related

• AI Accounts — link your personal provider accounts and see usage across desktop, web, and CLI
• Router — policy over which model answers
• KMS — where the credential is sealed
• Models — the catalogue served without any connection
• API Reference — every endpoint at api.hanzo.ai