API keys

API keys let agents, the CLI, SDKs, and downstream systems reach Busabase's /api/v1 API as you. A key is a credential: what it can do is set by the permission level you choose when you create it, and it stays valid until it expires or you delete it.

Create API Key: name the key, choose an expiration and a permission level.

Create API Key — name, expiration, and permission level, all set at creation.

Create an API key

Open Account → API Keys and click Create New Key.

Fill in the Name (so you can recognize its purpose later, e.g. "Content agent"), Expiration, and Permission level, then click Create.

The key is shown only once

Copy and store it immediately after creation. Once the dialog closes you cannot view it again — you would have to delete it and create a new one.

Expiration

Option	Notes
Never	For long-lived integrations; rotate it yourself
7 days / 30 days / 90 days / 1 year	Time-boxed; good for temporary jobs or scheduled rotation

The default is 30 days, and the maximum is 1 year. Once a key expires, requests using it return 401 and you need to create a new one.

Permission level

Each key has exactly one permission level, and a higher level includes every level below it:

Level	Name in the UI	Can do	Cannot do
`read`	Read-view-only	Read data within the signed-in user's permissions	Modify workspace content
`changeRequest`	Change Request	Read, and propose changes	Merge or directly apply changes
`write`	Write data	Read, propose, review and merge changes, and edit content directly	Administration and permanent deletion
`manage`	Manage	Includes write access, administration, and permanent node deletion	—

For agents, changeRequest is usually all you need. It can read data and propose changes, but it cannot merge its own proposals — a human still reviews them in the Inbox. Only grant write or manage when the job genuinely requires it.

You can still rename a key and change its permission level after creation: the key value and expiry stay the same, and raising the level asks for a second confirmation, because every existing holder gains the new permissions immediately.

How keys relate to workspaces

A key belongs to your account, not to a single workspace — it works in every workbench space you belong to (Bases, records, Change Requests, nodes).

To target a space, send the x-busabase-space header with the request (the CLI / SDK equivalent is the BUSABASE_SPACE_ID environment variable). If you belong to more than one space and omit it, the request is rejected as ambiguous — Busabase will not guess for you.

Call GET /api/v1/auth to see the space currently in effect and every space you belong to.

The permission level is also a ceiling: what a key can actually do is the intersection with your own role in that space.

Use a key in a request

Put the key in the Authorization header:

curl https://busabase.com/api/v1/auth \
  -H "Authorization: Bearer $BUSABASE_API_KEY" \
  -H "x-busabase-space: $BUSABASE_SPACE_ID"

Base URL: https://busabase.com (use your deployment's address for local or self-hosted).
Auth header: Authorization: Bearer <key>; x-api-key is also accepted.
Writing records: submit over /api/v1; records land in the Inbox for review.

For request shapes and examples see the REST API; for the full endpoint list see the OpenAPI reference.

Security practices

One key per agent. Don't share a single key across several agents — permissions and usage become impossible to tell apart. With separate keys you can use Busabase Insights to see which Change Requests and proposals each agent produced.
Least privilege. Start at the lowest level that gets the job done, and issue a separate key if you later need more.
Set an expiration. Use short-lived keys for temporary jobs and rotate long-lived ones.
Keep it out of the repo. Pass it via environment variables in CI and local development (BUSABASE_API_KEY, BUSABASE_SPACE_ID).
Delete on suspicion. Deleting a key immediately cuts off every caller using it (see below).

Manage and revoke

The Account → API Keys list shows each key's name, key prefix, created date, expiry, permission level, and actions.

Copy: available only right after creation; you cannot view the full key again afterwards.
Edit: change the name or the permission level.
Delete: revokes it immediately and cannot be undone. Integrations using the key lose access at once and need a new key.

Troubleshooting

Symptom	Likely cause and fix
`401` Unauthorized	The key is invalid, expired, deleted, or its owner's account is banned. Check the key and recreate it if needed.
Ambiguous space	You belong to several spaces and didn't send `x-busabase-space`. Add the target space ID.
`403` Forbidden	The key's permission level is too low for the operation (e.g. using `changeRequest` to merge a change). Use a higher-level key, or have a human do it.

See also: Core Concepts · Quick Start

Other ways to connect: Integration overview · CLI · SDK · MCP · REST API · OpenAPI · Webhooks

API keys

On this page