API Key Format

Chuizi.AI API keys are the primary authentication mechanism for all API requests. Each key is tied to a user account and can be individually configured with access controls, rate limits, and usage restrictions.

Key Format

Property	Value
Prefix	`ck-`
Body	32 alphanumeric characters (`a-z`, `A-Z`, `0-9`)
Total length	35 characters
Example	`ck-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

The ck- prefix identifies Chuizi.AI keys and allows tools to distinguish them from other API keys. The prefix is always lowercase.

Security Properties

Storage

API keys are never stored in plaintext. The gateway stores a securely encrypted hash of the full key. The ck- prefix and first four characters of the body (e.g., ck-a1B2) are stored separately as a human-readable identifier.

Stored	Value	Purpose
`key_hash`	Securely encrypted hash of full key	Authentication lookup
`key_prefix`	`ck-a1B2`	Display in dashboard, support queries

Display Policy

The full API key is shown exactly once at creation time. After you dismiss the creation dialog, the full key is not retrievable. If you lose a key, delete it and create a new one.

Authentication Flow

Client sends Authorization: Bearer ck-xxxxx (or x-api-key: ck-xxxxx).
Gateway computes the secure hash of the key.
Gateway looks up the hash in the authentication system.
If found and active, the request proceeds. If not, returns 401.

Key Management

Manage your API keys at app.chuizi.ai under the API Keys section.

Create a Key

Navigate to API Keys in the console sidebar.
Click Create Key.
Enter a name (e.g., "Production Server", "Claude Code").
Optionally configure access controls (see below).
Click Create.
Copy the displayed key immediately. You will not see it again.

Delete a Key

Deleting a key is immediate and irreversible. All requests using that key will begin returning 401 invalid_api_key.

List Keys

The dashboard shows all keys with their prefix, name, group, status, and creation date. Use the GET /v1/key/info endpoint to query key details programmatically.

Key Configuration Options

Each API key supports the following configuration properties.

Property	Type	Default	Description
`name`	`string`	Required	Human-readable name for identifying the key.
`group`	`string`	`null`	Optional grouping label (e.g., "production", "staging").
`allowed_models`	`string[]`	`[]` (all models)	Restrict the key to specific models. Empty array means all models are allowed. Uses `provider/model` format.
`ip_whitelist`	`string[]`	`[]` (no restriction)	Restrict requests to specific IP addresses or CIDR ranges. Empty array means all IPs are allowed.
`rpm_limit`	`number`	`null` (uses account default)	Override the per-key requests-per-minute limit.
`daily_limit`	`number`	`null` (no limit)	Maximum number of requests per day (resets at midnight UTC).
`is_active`	`boolean`	`true`	Whether the key accepts requests. Set to `false` to disable without deleting.

Example: Restricted Key

Create a key that only allows access to Claude models from a specific IP range with a conservative rate limit.

Property	Value
`name`	"Production Claude Only"
`allowed_models`	`["anthropic/claude-sonnet-4-6", "anthropic/claude-haiku-4-5"]`
`ip_whitelist`	`["203.0.113.0/24"]`
`rpm_limit`	`30`
`daily_limit`	`1000`

Key Info Endpoint

Query your key's configuration and current usage programmatically.

terminal

bash

curl https://api.chuizi.ai/v1/key/info \
  -H "Authorization: Bearer ck-your-key-here"

Response:

config.json

json

{
  "key_prefix": "ck-a1B2",
  "name": "Production Server",
  "group": "production",
  "is_active": true,
  "allowed_models": [],
  "ip_whitelist": [],
  "rpm_limit": 60,
  "daily_limit": null,
  "created_at": "2025-01-15T08:30:00Z"
}

Best Practices

One key per environment. Create separate keys for development, staging, and production.
Use allowed_models in production. Prevent accidental calls to expensive models.
Enable IP whitelisting for servers. Restrict production keys to your server IPs.
Rotate keys periodically. Create a new key, update your deployment, then delete the old key.
Never commit keys to version control. Use environment variables or secret managers.

Next Steps

API Key Best Practices — Secure storage, rotation, and leak response procedures
Sign Up — Create an account and generate your first key
Error Codes — Troubleshoot 401 and 403 authentication errors