Authentication

The gateway authenticates every request with a bearer key. A key belongs to one allocation, carries one or two scopes, and is the only credential the API accepts.

Base URL: https://cairva.xyz/v1

Send the key

Put the key in the Authorization header:

Authorization: Bearer cv_live_XXXXXXXX_...

OpenAI SDKs do this for you when you pass the key as apiKey (JavaScript) or api_key (Python). See SDKs.

Key format

A full key looks like cv_test_AbC12xYz_ followed by a long random secret. The eight characters after the mode are the key's public prefix. That prefix is what the workspace and audit logs show, so you can tell keys apart without exposing the secret.

Cairva stores only a keyed hash of the full key. A lost key can't be recovered, only rotated.

Scopes

Give each key the least it needs. A reporting job that reads usage only needs usage:read and can't spend your allowance.

One key, one allocation

Each key is bound to a single allocation. It can only call that allocation's model, spend that allocation's allowance and read that allocation's usage. To use two allocations, use two keys.

Failures

All authentication failures return 401 with "type": "authentication_error" and "code": "unauthenticated". The message tells you which case you hit:

A valid key without the scope an endpoint needs gets 403 scope_missing.

{
  "error": {
    "message": "scope_missing: this key lacks the \"usage:read\" scope",
    "type": "invalid_request_error",
    "code": "scope_missing"
  }
}