API keys

API keys are created in the workspace, one allocation at a time. Only admins of the buyer organization can create, rotate or revoke them.

Create a key

1. Open API keys in the workspace.
2. Choose the allocation. It has to be activated: ready, active or paused. Keys can't be created for a reserved allocation, or for one that's depleted, expired or terminated.
3. Name the key, 2 to 60 characters. Use a name that says where it runs, such as billing-worker-prod.
4. Pick scopes: inference, usage:read or both.
5. Copy the secret. It's shown once.

The key's mode follows the route: cv_live_ for live allocations, cv_test_ for sandbox ones. See Authentication.

Store it

• Put it in an environment variable or your secret manager, as CAIRVA_API_KEY.
• Keep it on servers. Never ship it in a browser bundle or a mobile app.
• Use separate keys for separate services, so you can revoke one without touching the others.
• Give reporting jobs usage:read only.

Cairva stores only a keyed hash of the full key, so nobody at Cairva can read it back to you.

Rotate a key

Rotating revokes the old key and issues a new one with the same name, allocation and scopes. The new secret is shown once, and the old key fails with 401 on its next request.

For a change with no downtime, create a second key for the same allocation, deploy it, then revoke the first.

Revoke a key

Revoking needs a reason of 3 to 300 characters, which goes into the audit log. A revoked key gets 401 unauthenticated with the message This API key was revoked. Cairva operations can also revoke a key, for example if it's found in public code.

See what a key is doing

The workspace lists each key's prefix, scopes, allocation and when it was last used. Each request also carries the key's allocation in its cairva object, and usage events show your x-request-id, so you can attribute spend to a service by sending a request id per caller.