Authentication

API keys

Every request authenticates with a per-organization API key sent as a Bearer token.

Authorization: Bearer ba_<key>

Keys are:

User-scoped — actions appear in the audit log under the user who created the key, with authMethod: "api_key".
Organization-scoped — a key only sees data in the organization where it was created.
Time-limited — every key has an expiration date.
Prefixed ba_ — the prefix enables automated secret scanning (GitHub, GitGuardian) to detect leaked keys.

Creating a key

Open Organization Settings → API Keys.
Click Create Key.
Give it a descriptive name (e.g. Mobile App, CI/CD Pipeline).
Pick an expiration (30 / 60 / 90 days, 1 year, or custom).
Click Create.

The secret is shown once. Copy it immediately and store it in a secrets manager — there is no way to retrieve it later.

Using a key

curl -H "Authorization: Bearer ba_..." https://your-domain/api/v1/workspaces

Failures return 401 Unauthorized for any of:

Missing or malformed Authorization header
Unknown key
Revoked key
Expired key
The key's owning user is banned

Key lifecycle

State	What happens
Active	Key authenticates successfully.
Expired	Past `expiresAt` — requests rejected with `401`. Cannot be reactivated.
Revoked	Manually revoked from the dashboard — requests rejected with `401`. Immediate and irreversible.

Revoke a key from Settings → API Keys → Revoke next to the row. Revocation takes effect immediately for all in-flight requests.

Security best practices

Never commit keys to source control.
Store keys in environment variables or a secrets manager.
Prefer short expiration periods.
Issue separate keys per application / environment.
Monitor the Last Used column to detect dormant keys.
Revoke any key that may have leaked.

Audit logging

Every mutation triggered via API key is recorded in the Activity Log with authMethod: api_key, the calling user's id, and the source IP/User-Agent — so leaked keys leave an investigable trail.