Organization API keys

An organization key works across your whole organization. Use it to create workspaces and to work in any of them.

Get a key

Clustr staff create the key for you. It starts with clo_ and is shown once. Store it like a password. You can hold several keys and revoke one without touching the others. Send it as a bearer token:

curl https://api.clustr-ai.com/api/org/v1/tenants \
  -H "Authorization: Bearer $CLUSTR_ORG_KEY"

The same key also works on the rest of the API once you name a workspace.

Scopes

A key carries scopes. A call without the right scope answers 403.

Scope	What it allows	Default
`tenants:write`	Create, rename, suspend, resume and delete workspaces	Yes
`jobs:write`	Write as a workspace: start and cancel imports and every other write	Yes
`data:read`	Read as a workspace: jobs, results, paths and every other read	Yes
`exports:manage`	Set the webhook, rotate its secret, read its deliveries	No
`usage:read`	Read usage, statements and limits	No
`erasures:write`	Erase a person from the whole organization	No

Listing and reading workspaces, and reading the audit log, need a valid key and no scope. Your organization’s admins create and revoke keys in the app, under Organization, API keys. A key created there gets tenants:write, jobs:write and data:read. For the other scopes, ask your Clustr contact.

What a key can reach

A key reaches every workspace in your organization. Any other workspace id answers 404.

Rate limit

Requests are limited per organization: all your keys and workspaces share one limit. Past the limit you get 429. Wait for the Retry-After header, then retry.

Audit log

Every call is recorded: which key, which workspace, what, and the result. GET /api/org/v1/audit-log returns your organization’s own trail, newest first. Use limit (default 100, at most 500).

Guides