# API keys

> Create, rotate and revoke keys for an allocation, and keep them out of client code.

Source: https://cairva.xyz/docs/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](https://cairva.xyz/docs/authentication#key-format).

## 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](https://cairva.xyz/docs/usage) show your `x-request-id`, so you can attribute spend to a service by sending a request id per caller.