API Key Authentication
Include your API key in theX-API-Key header:
Key Format
The checksum enables client-side format validation before making a request:
Key Types
Every key belongs to exactly one organization and acts only on that
organization, at the role it was given when it was minted. The person who
created the key is recorded for the audit trail; their other memberships never
extend the key’s reach, and a key created by an Owner is not an Owner. To act
on two organizations you need two keys.
Publishable keys (
cpk) differ from the other types in that they are:
- Scoped to a single organization (returns org context, not user context)
- Limited to a lower default rate (100 requests/minute) suited to client-side use
rate_limit_per_minute, rate_limit_per_day) and optional
expiration (expires_at) apply to every key type, not just publishable ones —
see Rate Limits.
Key Lifecycle
Keys are shown once at creation time. The raw key is never stored — only its SHA-256 hash.Organization Roles (RBAC)
Users belong to organizations through memberships, each with a role:
Roles are evaluated per-organization. A user can be an Owner of one organization and an Editor of another.
An API key has its own role (
manager, editor or readonly), evaluated the
same way but only ever on the key’s own organization. A readonly key minted by
an Owner can read that organization and nothing more.
Permission Reference
organization.tombstone_organization gates DELETE /organizations/{id}
itself — the reversible 90-day tombstone. organization.delete_organization
is the narrower, still fully human-only permission behind the truly
irreversible operations: fast-purge and restore.
OAuth Logins
closient auth login, and any app you sign in to Closient with, gets an OAuth
access token instead of a key. Send it as Authorization: Bearer <token>.
A login acts for one organization, like a key. When you approve it, on the
/device page or the app’s consent screen, Closient asks which organization it
is for:
- One organization: the login is for that one, and the page says so.
- Several: you choose one. Nothing is preselected.
- None: the login works for what needs no organization, such as generating QR codes.
404). If you leave its organization, the login
gets 403; it never moves on to another of yours.
To switch organizations, log in again and choose the other one. For the
CLI, run closient auth login. GET /account/api/v1/whoami reports the login’s
organization as oauth.organization, which is null when the login has none.
Logins approved before organizations were asked for have none. If you belong to
one organization, they act on it. If you belong to several, organization-scoped
requests get
409 until you log in again and choose one.Session Authentication
Browser-based access (Dashboard, admin) uses Django session cookies. This is automatic when logged in and is primarily for internal use. API integrations should always use API key authentication.Security Best Practices
- Never expose
csbkeys in client-side code — usecpkpublishable keys instead - Store keys in environment variables, not in source code
- Rotate keys periodically and revoke unused ones
- Use per-key rate limits on publishable keys to prevent abuse
- Set expiration dates on keys used for temporary integrations