Authentication

Every request carries an API key from the console. Keys start with ckr_.

Send the key

Send it as a Bearer token:

curl https://api.cloakray.com/v1/chat/completions \
  -H "Authorization: Bearer $CLOAKRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Hello"}]}'

Anthropic clients send x-api-key instead. Cloakray reads either header, on every endpoint.

Never put a key in a URL or a query string, and never ship one to a browser or a mobile app: anyone holding it can spend your balance. Call Cloakray from your server and keep the key in an environment variable or a secret manager.

What a key belongs to

A key belongs to one project, and the project belongs to an organization. Every request a key makes is billed to that organization and shows up in that project's logs and analytics. Create one key per app or environment so usage stays apart and a leaked key can be replaced without touching the others — see API keys and projects.

When authentication fails

Status	Meaning
`401`	The key is missing, malformed, deleted, or has been rolled. Check the header and the key.
`429`	Too many requests, or too many failed attempts. Wait for `Retry-After`.
`503`	The key could not be checked right now. It may be perfectly valid; retry shortly. Nothing was sent or charged.

Check a key from the API

GET /v1/key describes the key making the request: its name, its spend so far, and for a Token Plan key, the plan's credit.

curl https://api.cloakray.com/v1/key \
  -H "Authorization: Bearer $CLOAKRAY_API_KEY"

{
  "data": {
    "label": "Production",
    "usage": "12.48",
    "limit": null,
    "devPlan": "none",
    "devPlanCreditsUsed": "0",
    "devPlanCreditsLimit": "0",
    "devPlanCreditsRemaining": "0"
  }
}

Amounts are USD, as strings. usage is what this key has spent.

GET /v1/credits returns the organization's prepaid balance and its total spend:

{ "balance": "87.52", "total_used": "112.48" }

Both endpoints are free and describe only your own organization. They are handy as a health check in a deploy script, or to warn before a balance runs out.

Browser requests

The API answers cross-origin requests, so tools that run in a browser — notebooks, local playgrounds — can call it. That does not make a browser a safe place for a key: use it only with a key you own on a machine you control.