Authentication and API keys

Every REST API request authenticates as your organization with an API key, sent as a bearer token. A key can carry a scope: which kinds of changes it may make, and which agents it may touch. Give each system its own key, scoped to what that system needs, so a leaked key can do as little as possible.

Authorization: Bearer <your API key>

The one exception is the Web SDK, which runs in a browser and uses a short-lived session pass that your server mints with an API key.

Creating a key#

Open Settings → API keys (where available) and select Create API key. If your organization doesn't show that item, open Settings → Members, which opens your organization's account page, and manage keys in its API Keys section.

On Settings → API keys:

1. Enter a Description that names the system that will use the key, such as Acme Corp integration, so an unfamiliar key in a log can be traced back to its owner.
2. Choose the key's capabilities and, if it should reach only some agents, fill in the Agent allowlist. Both are explained below.
3. Select Create key. The key is shown once. Copy it into your secret manager before you close the dialog.

The capability switches and the agent allowlist are edited only on Settings → API keys, or through the API with a key that holds manageApiKeys. A key created on the organization's account page carries no scope, and behaves like a key created before scopes.

Capabilities#

A capability allows a kind of change. Reads need only a valid key, with one exception: listing API keys requires manageApiKeys.

manageApiKeys is effectively full admin access: a key that can create keys can create one with every capability. Keep it for internal automation and never hand it to a client.

A change whose operation declares no capability requires manageAgents.

Agent allowlist#

An empty allowlist means the key can reach every agent in the organization, including agents created later. A key with an allowlist is limited to the agents on it:

• A request that addresses an agent outside the list, by path, body or query, or through a thread that belongs to one, is refused with 403 forbidden_by_agent_allowlist. That includes GET /v1/threads?assistant_id= for such an agent.
• Two list endpoints filter instead of refusing: GET /v1/assistants and GET /v1/agents?ids= silently leave out agents outside the list.
• Organization settings are off limits. The credits, API keys, AI Gateway, Google Drive service accounts and integration suggestions endpoints answer 403 forbidden_org_endpoint_for_scoped_key, reads included.

How a request is checked#

Each request passes three gates in order, and the first one that fails decides the 403:

1. Capability (changes only): does the key hold the capability the operation requires? Otherwise forbidden_by_key_role.
2. Organization settings: is this an organization-level endpoint and the key limited to an allowlist? Then forbidden_org_endpoint_for_scoped_key.
3. Allowlist: is the addressed agent outside the key's list? Then forbidden_by_agent_allowlist.

Every operation falls into one of three classes: agent-scoped (it addresses an agent, so the allowlist applies), org-config (organization settings, refused for allowlisted keys) and catalog (organization-independent data; neither gate applies). The OpenAPI document publishes each operation's class and required capability as the x-runbear-scope extension, and describes the vocabulary once at its root under x-runbear-api-key-scopes.

Keys without a scope#

Keys created before capabilities existed, and keys created on the organization's account page, have no scope. They can chat and manage agents, and reach every agent, but they cannot manage API keys: listing, creating or revoking keys through the API needs a key created with manageApiKeys.

Managing keys through the API#

All four operations require a key with manageApiKeys and no agent allowlist.

curl -s https://api.runbear.io/v1/api-keys \
  -H "Authorization: Bearer $RUNBEAR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Support portal",
    "canChat": true,
    "canManageAgents": false,
    "allowedAgentIds": ["<agent id>"]
  }'

Revoking#

Revoking a key takes effect immediately and cannot be undone. Requests using it fail with 401 api_key_invalid, so switch the consumer to its replacement first. Revoke on Settings → API keys, on the organization's account page, or with DELETE /v1/api-keys/{id}.

Authentication errors#

A 401 carries a code that says why:

Only pass_expired is retryable. Treat a code you don't recognize as terminal: the list only grows.

When key validation itself is throttled, the request fails with 429 and a Retry-After header rather than a 401. The key is fine; wait and retry. For every 403 and 429 code, see Errors and limits.

Related#

• REST API overview
• Errors and limits
• Web SDK session mode — session passes for browsers
• MCP server — manage agents from an AI client, authenticated by OAuth rather than a key