Authentication

Reference article: Part of the API reference. To create and manage keys, see API keys.

The Nimbus API authenticates every request with an API key sent as a bearer token. There are no sessions or cookies: a request without a valid key is refused before it reaches any data.

Authorization: Bearer nmb_sk_4f9KqLz2Vw8RtY6uP3xN1mB7cD5eF0gHx9Qa

::: code-group

curl https://api.gonimbus.ai/v1/whoami \
  -H "Authorization: Bearer $NIMBUS_API_KEY"

const nimbus = (path: string, init: RequestInit = {}) =>
  fetch(`https://api.gonimbus.ai/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.NIMBUS_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  })

const response = await nimbus('/whoami')

import os
import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NIMBUS_API_KEY']}"

response = session.get("https://api.gonimbus.ai/v1/whoami")

:::

Key types

Every key starts with a prefix that says what it is, so you can tell keys apart in logs and secret scanners.

Prefix	Type	Access
`nmb_sk_`	Secret key	Every resource, in the workstreams you give it.
`nmb_rk_`	Restricted key	Only the resources and access levels chosen when the key was created.

After the prefix comes a 40-character random string. Keys don't expire unless you roll them with a grace period (see Rolling a key).

Scopes

A restricted key holds scopes, one per resource and access level, such as messages:write or runs:read. Secret keys hold every scope, shown as *.

Scope	Allows
`resource:read`	Listing and retrieving that resource.
`resource:write`	Creating, changing, and deleting it. Write includes read.

The resources you can scope a key to:

Resource	What it covers
`workstreams`	Workstreams and their settings
`messages`	Messages in workstream and Conflux rooms
`agent`	Asking the workstream agent and streaming its answer
`runs`	Runs, their status, and their reports
`loops`	Loops and their executions
`documents`	Uploaded documents and search
`connections`	Connected apps and their status
`decisions`	Recorded decisions and their evidence
`apps`	Nimbus Apps and their installs
`webhooks`	Webhook endpoints and deliveries
`tasks`	Tasks and task projects, over the Nimbus MCP server and the API

A request that needs a scope the key doesn't hold fails with 403 and the code insufficient_scope. The message names the missing scope.

Workstream access

Scopes aren't the only limit. Whatever its scopes, a key reaches only the workstreams it has been granted on the Developers page and the workstreams it created itself. Anything in another workstream answers 404 resource_missing, as if it didn't exist. See Workstream access.

When authentication fails

Status	Code	Cause
`401`	`missing_api_key`	No `Authorization` header, or it isn't `Bearer <key>`.
`401`	`invalid_api_key`	The key doesn't exist, or is mistyped.
`401`	`api_key_revoked`	The key was revoked, or rolled with no grace period.
`401`	`api_key_expired`	The key was rolled and its grace period ended.
`403`	`insufficient_scope`	The key works, but may not do this.
`403`	`organization_unavailable`	The organization the key belongs to can't be found.

Requests refused because the key was revoked or expired still appear in your request log, so you can find the service still using an old key.

Keeping keys safe

Keep keys on servers. Load them from a secret manager or environment variable. Never commit them, and never ship a key in a browser bundle or mobile app, where anyone can read it.
Give each integration its own key. Then you can roll or revoke one without breaking the others, and the request log shows which integration made each call.
Prefer restricted keys. A CI bot that posts messages needs messages:write, not your whole organization.
Grant only the workstreams a key needs. A key given one workstream can't touch the others. See Workstream access.
Roll on suspicion. If a key may have leaked, roll it with no grace period. The old key stops working immediately.

Note: The keys you use in the Nimbus API are separate from how people sign in to Nimbus. Keys can't be used to sign in to the app, and a person's login can't call the API.

FAQ

Why am I getting 401 missing_api_key when I'm sending a key?

The header must be exactly Authorization: Bearer <key>, with a space after Bearer. Some HTTP clients drop the Authorization header when they follow a redirect, so send requests straight to the https:// URL.

Can I send the key as a query parameter?

No. Keys in URLs end up in proxy logs and browser history, so the API only reads the Authorization header.

Does a key act as the person who created it?

No. A key acts for the organization. The person who created it is recorded, but the key keeps working if they leave, and its access depends only on its scopes and the workstreams it has been given.

How do I know which key a request used?

Call GET /v1/whoami with the key, or open the request on the Developers page, which shows the key's name for every logged request.

What if my key leaks?

Roll it on the Developers page with Now as the grace period. The leaked key stops working immediately, and you get a new one with the same name and scopes to deploy.