Caicaini
Get started

Getting started

Authentication

Every request to /v1/* is authenticated with a bearer token. There is no IP allow-list, no signed request, no nonce — just a Caicaini API key in the Authorization header.

Key format

Caicaini API keys start with the prefix cai_api_ followed by 32 random characters from a URL-safe alphabet. The full key is shown once at creation time and cannot be retrieved later. Only the first 12 characters (the prefix plus a few random bytes) are stored in plaintext on our side, so they can be displayed in your dashboard and our logs without exposing the secret.

We hash the rest with argon2id and verify in constant time on every request. There is a 5-minute Redis cache on the hot path to keep the verification cost near zero.

Authorization header

Pass the key as a bearer token. The header name is case-insensitive but the scheme is not — it must read Bearer, with one space, then the key.

header
Authorization: Bearer cai_api_YOUR_KEY

Verify your key

The cheapest way to confirm a key is wired up correctly is to call GET /v1/account. It returns your current rate-limit tier, your spendable credit balance, and how many credits you have consumed this month. The endpoint does not run a model and does not charge credits.

curl https://caicaini.com/v1/account \
  -H "Authorization: Bearer cai_api_YOUR_KEY"

What you get when auth fails

Authentication failures return HTTP 401 with this body shape. There is no body for a missing Authorization header beyond the standard error envelope.

response · 401
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}

See Errors for the full set of failure types and their causes.

Storing keys safely

  • Put the key in an environment variable (CAICAINI_API_KEY), a secret manager, or a sealed deploy config. Never commit it to a repo or ship it inside a web bundle.
  • The key authenticates as your account. Anyone with the key can spend your apiCredits until you revoke it.
  • For browser apps, proxy through a server you control. The browser must never see the key.
  • Use one key per environment (dev, staging, prod) and one per service. That way revoking a leaked key only affects the surface that leaked it.

Rotating and revoking

Visit /developers/keys to mint, list, and revoke keys. Revocation is immediate. The 5-minute Redis cache is invalidated on the same transaction, so a revoked key cannot make another call within seconds.

We recommend creating the new key, deploying it, then revoking the old key. Active keys per account are limited to 25 — if you hit the cap, revoke unused entries first.

Scopes

Every key carries a list of scopes. The default for new developer keys is messages.create, models.read, and usage.read — enough for everything documented in this reference. We will add narrower scopes (read-only keys, batch-only keys) before they are enforceable on a per-key basis. Until then, treat the key as full-access to the API surface.

NextModels