Authentication

There is one HTTP scheme: authorization: Bearer. What the credential reaches depends on its prefix, not the header it travels in.

Key	Reaches	Held by
Management key (`nsk_`)	Every Brain in one organization, plus creating Brains and minting Brain keys	Your backend
Brain key (`nbk_`)	One Brain, with only the capabilities you granted	An app, a department, an end user, an agent

A Brain key is bound to one Brain, so it never needs to be told which one. A management key is bound to one organization the moment it is minted, so it doesn’t either.

Management keys

Sign in at app.nicia.ai, open Settings → API keys, and mint one under Organization keys. The secret is shown once and stored only as a hash — copy it now; a lost key is replaced, never recovered.

curl https://api.nicia.ai/v1/brains \
  -H "authorization: Bearer $NICIA_KEY"

That’s it — no second id to send. The key is bound to the organization it was minted from, so every call it makes reaches that organization and no other.

Minting one over HTTP

POST /v1/keys mints a key, GET /v1/keys lists them, and DELETE /v1/keys/{id} revokes one — all three from a signed-in browser session, never from a key, in either header: a valid management key is refused with 403 forbidden here, because a credential that can mint its own successor would outlive its own revocation. That is why the console above is the first step, and this is the automation path afterwards.

curl -X POST https://api.nicia.ai/v1/keys \
  -H "cookie: $NICIA_SESSION" \
  -H "x-organization-id: $NICIA_ORG" \
  -H "content-type: application/json" \
  -d '{ "name": "provisioning service" }'

{
  "data": {
    "key": {
      "id": "key_2d90ff",
      "name": "provisioning service",
      "organizationId": "org_4471",
      "status": "active",
      "createdAt": "2026-08-14T09:15:41Z"
    },
    "secret": "nsk_…"
  }
}

The secret is returned exactly once. expiresAt, if you send one, must be between 1 and 365 days out. Every call mints a new key — this endpoint is not idempotent.

A management key authorizes only while the person who minted it is still a member of that organization: remove them and their keys stop on the next request, everywhere. Mint from an account the organization keeps if the credential has to outlive any one employee, and revoke explicitly rather than relying on an offboarding checklist.

curl https://api.nicia.ai/v1/keys \
  -H "cookie: $NICIA_SESSION" \
  -H "x-organization-id: $NICIA_ORG"

curl -X DELETE https://api.nicia.ai/v1/keys/key_2d90ff \
  -H "cookie: $NICIA_SESSION" \
  -H "x-organization-id: $NICIA_ORG"

Listing includes revoked keys, so the audit trail survives, and never returns a secret. Revoking is idempotent, and takes effect on the next request everywhere. It disables the row rather than deleting it, so it stays listed — the console’s confirm dialog says so before you click through.

Use a management key when your own backend is the only thing holding it: a provisioning service, a nightly sync job, a server-side agent that works across many customers. It is the right key for the Quickstart because there is nothing to set up before you can use it.

x-api-key still works — for management keys

The server also accepts a management (nsk_) key in x-api-key — the CLI and older integrations use it, and it isn’t going away. A management key minted from Organization keys in the console, or from /v1/keys, is bound to the organization it was minted from and never needs x-organization-id. A management key minted before /v1/keys existed carries no binding: name the organization explicitly with x-organization-id, on every call, or a write is refused with 400 validation rather than guessed at. See the changelog for when binding shipped.

This is about management keys only. Personal app_ keys — minted from Your keys, on the same Settings → API keys screen — are a different plane and are not covered by any of the above: they are never bound to an organization, so they still need x-organization-id on every write, and they are not being changed in this wave. Send a personal key in x-api-key, never in authorization: Bearer — that scheme is read by prefix, an app_ secret sent there is looked up as a Brain key, and misses with 401 unauthorized (“Brain key is not active”) instead of the real problem.

Brain keys

A Brain key reaches exactly one Brain, with exactly the capabilities you list:

curl -X POST https://api.nicia.ai/v1/brains/tenant:acme/keys \
  -H "authorization: Bearer $NICIA_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Acme web app",
    "capabilities": ["read"]
  }'

{
  "data": {
    "key": {
      "id": "key_7f3a1c",
      "name": "Acme web app",
      "capabilities": ["read"],
      "status": "active",
      "createdAt": "2026-08-14T09:15:41Z"
    },
    "secret": "nbk_…"
  }
}

Use one whenever the holder is not you: a customer-facing app, an end user’s Claude Code, an agent you did not write, a department inside a company whose IT team provisioned the Brain. A leaked Brain key reaches one customer’s Brain with one capability set, and revoking it touches nothing else. Minting, rotating, and revoking a Brain key are management-key operations — the Brain key itself is what you hand to the holder.

Capabilities

Capability	Grants
`read`	`/context`, `/search`, `/query`, reading records and receipts, and the Brain’s own name, purpose, and mode
`write`	`/documents`, record writes, `/batch`
`review`	Listing and settling changes
`admin`	`PATCH /v1/brains/{handle}` — the review switch — but not reading the Brain’s contents

admin deliberately grants no access to knowledge: administering a Brain is not a reason to read what it knows. It is the capability that turns review on and off, so a service that flips Brains between open and reviewed needs an admin key and nothing more.

That separation is only worth anything if it holds for bulk egress too, so admin carries neither export nor webhook control: an admin key cannot start a bulk export or point a webhook at change payloads. Schema evolution, webhooks, and export have no v2 endpoint yet — when they arrive they get their own capability rather than being folded into admin, and the changelog will say so. The API reference is the list of what each capability reaches today.

Whether writes land or stage is not a capability at all: it is the Brain’s mode, set on the Brain itself.

Four things are management-key only, and no Brain key grants them, at any capability: creating a Brain (PUT /v1/brains/{handle}), deleting one, listing the organization’s Brains, and minting, rotating, revoking, or listing a Brain’s keys. A key that could mint its own successor would make revocation meaningless, and a Brain key cannot exist before its Brain does.

Presets exist for the common shapes — reader (read), contributor (read, write), reviewer (read, review) — and expand to exactly those arrays before the request leaves.

Rotating and revoking

# Mint a replacement; the old secret keeps working until you revoke it
curl -X POST https://api.nicia.ai/v1/brains/tenant:acme/keys/key_7f3a1c/rotate \
  -H "authorization: Bearer $NICIA_KEY"

curl -X DELETE https://api.nicia.ai/v1/brains/tenant:acme/keys/key_7f3a1c \
  -H "authorization: Bearer $NICIA_KEY"

Rotation gives you an overlap window so a running fleet does not drop requests. Revocation is immediate.

Which key should I use?

Provisioning a Brain per customer from your backend → management key.
Your server-side agent reading many customers’ Brains → management key.
Shipping a key inside an app, a browser, or an end user’s tool → Brain key.
Corporate IT creating a Brain per department and handing it over → Brain key per department.

If a key would ever leave a machine you control, it should be a Brain key.

Errors

A missing or invalid key is 401 unauthorized. A valid key without the required capability is 403 forbidden, and the message names both the capability the operation needed and the ones your key holds. Too many requests is 429 rate_limited with a Retry-After header. See Errors.

Handing out keys — patterns for fleets and end users.
Quickstart — a key to an answer in three calls.