Authentication

The Zihin API supports two authentication methods. Use an API Key (sent as X-Api-Key or Authorization: Bearer) for public endpoints and server-to-server calls; use a JWT token with an x-tenant-id header for multi-tenant apps that carry per-user context. Each endpoint accepts one or the other — see the summary table.

API Key Authentication

Use API Key authentication for public endpoints and simple server-to-server integrations.

Headers

X-Api-Key: YOUR_API_KEY

Or as Bearer token:

Authorization: Bearer YOUR_API_KEY

Example

curl -X POST https://llm.zihin.ai/api/v3/llm/public/call \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello", "model": "auto"}'

Key Format

Environment	Format	Example
Production	zhn_live_*	zhn_live_abc123
Sandbox	zhn_test_*	zhn_test_xyz789

JWT Authentication

Use JWT authentication for multi-tenant applications that pass end-user context on each request.

Required Headers

Authorization: Bearer <jwt-token>
x-tenant-id: <uuid>
x-agent-id: <uuid>
Content-Type: application/json

Example

curl -X POST https://llm.zihin.ai/api/v3/llm/call \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "x-tenant-id: YOUR_TENANT_UUID" \
  -H "x-agent-id: YOUR_AGENT_UUID" \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello", "model": "auto"}'

Header Reference

Header	Required	Description
Authorization	Yes	JWT token from your identity provider
x-tenant-id	Yes	Tenant UUID for isolation
x-agent-id	Yes	Agent UUID for tracking
Content-Type	Yes	Must be application/json

Endpoint Authentication Summary

Endpoint	API Key	JWT
/api/v3/llm/public/call	Yes	No
/api/v3/llm/call	No	Yes
/api/llm/models	No	No
/api/health/*	No	No
/api/agents/*	No	Yes
/api/database-configs/*	No	Yes
/api/telemetry/*	No	No

Error Responses

Invalid API Key

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired",
  "status": "error"
}

Missing Authentication

{
  "error": "authentication_required",
  "message": "This endpoint requires authentication",
  "status": "error"
}

Invalid JWT

{
  "error": "invalid_token",
  "message": "JWT token is invalid or expired",
  "status": "error"
}

Common questions

Which authentication method should I use?

Use an API Key for public endpoints (/api/v3/llm/public/call), scripts, and server-to-server calls. Use a JWT token with x-tenant-id for multi-tenant apps where each request acts on behalf of a specific tenant and agent. See the endpoint summary.

Why am I getting a 401 or authentication_required?

Either the endpoint requires authentication you didn't send, or your key/token is invalid or expired. Confirm the endpoint's requirement in the summary table, and check that your API key uses the right prefix — zhn_live_ for production, zhn_test_ for sandbox.

What is the difference between zhn_live_ and zhn_test_ keys?

zhn_live_ keys run against production; zhn_test_ keys run against the sandbox environment. Both are sent the same way — see Key Format.