Authentication

Key format

All Codex Key tokens are prefixed with sk-clb- and have 43 characters after the prefix:

sk-clb-AbCdEfGhIjKlMnOpQrStUvWxYz0123456789

Keys are encrypted at rest (AES-GCM) and shown in full only once, at creation time. Only the last 4 characters and metadata (name, created at, last used) remain visible in the dashboard.

HTTP header

Send the key in the Authorization header using the Bearer scheme:

Authorization: Bearer sk-clb-...

curl example:

curl https://codexkey.ru/v1/models \
  -H "Authorization: Bearer sk-clb-..."

Python example with the OpenAI SDK:

from openai import OpenAI

client = OpenAI(
    api_key="sk-clb-...",
    base_url="https://codexkey.ru/v1",
)

resp = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Key rotation

Recommended rotation interval: at least every 90 days. Safe rotation flow:

1. Create a new key in the dashboard (name: prod-v2).
2. Roll it out to production (env var, CI/CD secret, vault).
3. Verify the new key works (check /cabinet/logs).
4. Revoke the old key with Revoke in the dashboard.

If a key is compromised, revoke it immediately — revocations propagate within seconds.

Storing secrets

• Never commit a key to a repository. Use .env + .gitignore or a secret manager (Vault, AWS Secrets Manager, GitHub Secrets).
• Do not put a key in frontend code — it would ship in the bundle and be visible to every user. Proxy requests through your own backend.
• For CLI tools, use keychain (macOS), secret-tool (Linux), or an encrypted config file.

Scopes (planned)

In the current version every key has full access to its account. Roadmap items include scoped keys:

• chat:write — access to /v1/chat/completions.
• responses:write — access to /v1/responses.
• models:read — access to /v1/models.
• billing:read — read limits and balance.

Audit and monitoring

Every request is logged in /cabinet/logs with:

• timestamp,
• model,
• token counts (prompt / completion / reasoning),
• cost in RUB,
• HTTP status,
• key ID (last 4 characters).

Anomalous spikes (for example, +500% requests in one hour) automatically trigger an email alert to the account owner.

Authentication error codes

Code	Cause
401	Key missing, invalid, revoked, or wrong prefix.
402	Key valid but account balance is zero.
403	Key valid but action forbidden (for example, account is locked).
429	Rate limit exceeded (RPM/TPM) — retry with exponential backoff.

See the API reference for full details.