# Authentication

> API keys plus your Account ID on every request.

Code Buckets uses the same **API keys** as the rest of the Clatter Labs Console. Create them in [Console › API keys](https://console.clatterlabs.com/api-keys). Each request carries two headers:

<ParamField header="Authorization" type="string" required>
`Bearer clsk_...`: your API key.
</ParamField>
<ParamField header="X-Clatter-Account" type="string" required>
The Account ID that owns the key, like `CL-7K2M9QXA` (Console › Settings). Matching is case-insensitive.
</ParamField>

```bash
curl https://api.codebuckets.clatterlabs.xyz/v1/projects \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Permissions

Give a key only what it needs:

| Permission | Allows |
| --- | --- |
| `buckets:read` | List and read projects, buckets, objects, the code tree, files, events, backups; download; usage |
| `buckets:write` | Create, update and delete projects and buckets; upload; delete objects |
| `backups:write` | Create, restore and delete backups |
| `account:read` | Read usage (`GET /v1/usage`) |

A key with none of the Code Buckets permissions answers `403 insufficient_scope`.

| Situation | Response |
| --- | --- |
| No `X-Clatter-Account` | `401 missing_account_id` |
| Account ID doesn't own the key | `401 account_mismatch` |
| Key wrong or revoked | `401 invalid_api_key` |
| Key expired | `401 expired_api_key` |
| Key lacks the permission | `403 insufficient_scope` |

## Rate limits

Each key has a per-minute limit you choose in the Console (10, 30, 60 or 120). Chunk uploads and chunk downloads don't count toward it, so big transfers aren't throttled by it. Over the limit answers `429 rate_limited` with `Retry-After`.

Revoking a key in the Console stops it within 30 seconds.

## CORS

The API allows cross-origin requests. Keep keys on your server anyway: never put a `clsk_` key in front-end code.