Authentication - Clatter Labs Docs

Code Buckets uses the same API keys as the rest of the Clatter Labs Console. Create them in Console › API keys. Each request carries two headers:

Authorizationstringrequired

Bearer clsk_...: your API key.

X-Clatter-Accountstringrequired

The Account ID that owns the key, like CL-7K2M9QXA (Console › Settings). Matching is case-insensitive.

Terminal

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.