# API keys



Organization API keys authenticate LLM Gateway inference and supported
organization automation. Every key belongs to one organization, and metered
usage is billed to that organization.

Keys look like this:

```
ccp_live_ak_<key-id>.<secret>
```

Only a hash of the secret is stored. The full key is shown once, at creation.

## Create a key in the Console [#create-a-key-in-the-console]

1. Open the [Console](https://console.clusterbase.ai) and select your
   organization.
2. Open the menu on your name at the bottom of the sidebar, choose **Settings**,
   then go to **API keys** and click **Create API key**.
3. Enter a **Name** that describes where the key will live — for example
   `Production inference`.
4. Optionally open **Advanced settings** to set an expiration date. Keys
   without an expiration stay valid until you revoke them.
5. Click **Create key**.

The dialog then shows the full key one time. Copy it and store it in your
secret manager before you close the dialog — you cannot retrieve it again. The
key list only ever shows the key ID and the last characters of the secret.

## Use the key [#use-the-key]

Send the key as a bearer token on every request:

```bash
curl https://llm.clusterbase.dev/v1/models \
  -H "Authorization: Bearer $CLUSTER_API_KEY"
```

Every newly minted key carries the same fixed scopes:

| Scope            | Grants                                            |
| ---------------- | ------------------------------------------------- |
| `models:read`    | `GET /v1/models`                                  |
| `chat:stateless` | `POST /v1/chat/completions` and `POST /v1/chat`   |
| `agents:use`     | Organization-owned Agent definition operations    |
| `compute:use`    | Organization-owned Sandbox and Compute operations |

Use the same key with `ccp` automation without saving it as an OAuth session:

```bash
export CCP_API_KEY="ccp_live_ak_…"
export CCP_ORG_ID="org_…"
ccp compute list --org-id "$CCP_ORG_ID"
```

Chat API, persisted chats, personal Agent resources, membership, billing
administration, and API-key management remain human-authenticated. Existing
keys keep the scopes they were minted with; mint a new key to receive newly
added fixed scopes.

## Revoke a key [#revoke-a-key]

Open the key's row menu in the Console and choose **Revoke key**. Revocation
is immediate and permanent: requests using the key are rejected from that
moment, and the key cannot be restored. Requests with a revoked, expired, or
unknown key receive `401 authentication_error`.

## Errors [#errors]

| Status | Meaning                                                     |
| ------ | ----------------------------------------------------------- |
| `401`  | Missing, invalid, expired, or revoked key                   |
| `402`  | The organization has no active plan or credits              |
| `403`  | The key lacks the required scope                            |
| `503`  | The credential authority is temporarily unavailable — retry |