Secrets & Provider Keys

Zihin uses an encrypted vault (AES-256-GCM) to store sensitive credentials. Secrets are scoped per tenant and never exposed in logs or API responses.

Secret Categories

Category	Use	Examples
api_key	General-purpose API keys	Resend, Stripe, internal tokens
api	External service credentials	ERP auth, database passwords
llm_provider	Your own LLM API keys (BYOK)	OpenAI, Anthropic, Google, Grok
database	Database credentials	PostgreSQL passwords
custom	Other secrets	MCP server tokens, webhook secrets

---

Bring Your Own Key (BYOK)

You can configure your own LLM provider API keys. When configured, your agents will use your keys instead of the Zihin pool — without consuming your token quota.

How it works

1. You register your provider key as a secret
2. When an agent makes an LLM call, Zihin checks if you have a key for that provider
3. If yes: uses your key (no quota consumption)
4. If your key fails (expired, invalid): automatically falls back to the Zihin pool (consumes quota)

Supported providers

Provider	Secret name	Key format
OpenAI	provider_key_openai	sk-proj-... or sk-...
Anthropic	provider_key_anthropic	sk-ant-...
Google	provider_key_google	AIzaSy...
Grok (X.AI)	provider_key_grok	xai-...

Configuring via Console

1. Go to Settings > Secrets
2. In the LLM Provider Keys section, click Configure on the desired provider
3. Paste your API key and save
4. The key is encrypted and stored securely

Configuring via API

curl -X POST "https://llm.zihin.ai/api/secrets" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "X-Tenant-Id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "provider_key_openai",
    "value": "sk-proj-your-key-here",
    "category": "llm_provider",
    "description": "My OpenAI key"
  }'

Configuring via MCP (Claude Desktop / Cursor)

Use the manage_secrets tool:
- Action: create
- Name: provider_key_openai
- Value: sk-proj-your-key-here

Checking which providers have BYOK

GET /api/v1/tenant/byok-providers

Response:
{
  "providers": {
    "openai": true,
    "anthropic": false,
    "google": false,
    "grok": true
  }
}

---

BYOK and Model Access

When you configure BYOK for a provider, all models from that provider become available regardless of your plan tier. This means:

• Core plan with BYOK OpenAI: you can use openai.o3 (flagship) with your own key
• The same model via Zihin pool would be blocked (Core only allows economical + premium)
• If your key fails, the fallback to Zihin pool respects your plan's tier restrictions

Fallback chain example

Agent config:
  Primary:    google.gemini-2.5-pro (BYOK)     -> your key, no quota
  Fallback 1: openai.gpt-4.1-mini (pool)       -> Zihin pool, consumes quota
  Fallback 2: grok.grok-3-mini (BYOK)          -> your key, no quota

---

Plan requirements

Plan	BYOK available
Starter (free)	No
Core	Yes
Pro	Yes
Business	Yes

---

General Secrets

For non-LLM secrets (API keys for external services, database credentials, MCP server tokens), use the general secrets management:

1. Go to Settings > Secrets
2. Click Add Secret
3. Choose the appropriate category
4. Enter name, value, and optional description
5. Save — the value is encrypted immediately

Secrets are used by:

• API tools: secret_ref field in tool configuration
• MCP servers: vault_secret_id for authentication
• Triggers: webhook signature secrets, email API keys
• Database connections: vault_secret_id for credentials