BrainAPI Authentication and Brains

For the complete BrainAPI documentation index, see llms.txt. A markdown version of any docs page is available by appending .md to its URL. Docs MCP: /docs/mcp.

Protected core requests need a valid PAT. Most data requests also need a brain identifier. Treat the token as authorization and the brain as the data boundary; do not infer either from user-provided content.

Token types

Token	Scope	Use it for
System `BRAINPAT_TOKEN`	All brains and `/system/*`	Administration, brain creation, trusted operations.
Brain PAT	One stored brain	Application requests limited to that brain.

Send either header form:

BrainPAT: <token>

Authorization: Bearer <token>

Examples in these docs use BrainPAT because it avoids ambiguity with other bearer-token middleware.

Select a brain

BrainAPI resolves a brain in this order:

X-Brain-ID header.
brain_id query parameter.
Top-level brain_id in a JSON body for POST, PUT, or PATCH.
brain_id multipart field for file uploads.

Use X-Brain-ID in new integrations so routing is consistent across methods and body formats.

curl http://localhost:8000/meta/entity-labels \
  -H "BrainPAT: $BRAINPAT_TOKEN" \
  -H "X-Brain-ID: supportkb"

Brain IDs must be alphanumeric in ordinary data requests. The reserved system brain cannot be used as application data.

Create or resolve brains

BRAIN_CREATION_ALLOWED=true lets middleware create a missing named brain when a valid request selects it. DEFAULT_BRAIN_FALLBACK=true selects or creates default when no brain is supplied. For explicit administration, use the system token:

curl --fail-with-body -X POST http://localhost:8000/system/brains \
  -H "BrainPAT: $BRAINPAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"brain_id":"supportkb"}'

For production, prefer explicit brain creation and pass the intended brain on every request. Automatic creation is convenient during development but can hide spelling mistakes.

Resolve a token

GET /meta/login-info is exempt from brain selection and tells a console or client whether a PAT is the system token or belongs to one brain.

curl http://localhost:8000/meta/login-info \
  -H "BrainPAT: $BRAINPAT_TOKEN"

Rotate a brain access key

Replace a brain's PAT with the system token. On success the old PAT is invalidated and the response includes the new PAT.

curl -X POST http://localhost:8000/system/brains/supportkb/rotate-pat \
  -H "BrainPAT: $BRAINPAT_TOKEN"

Status	Code	Meaning	Check
`200`	n/a	PAT replaced. The response carries the new PAT.	Store it in your secret manager before closing the response.
`400`	`BRAIN_ID_INVALID`	Brain ID is malformed.	Use letters and numbers, starting with a letter.
`404`	`BRAIN_NOT_FOUND`	Brain does not exist.	List brains and use an existing ID.
`409`	`BRAIN_LIFECYCLE_BUSY`	Another lifecycle operation is running on this brain.	Wait for it to finish, then retry.
`503`	`BRAIN_PAT_CACHE_INVALIDATION_FAILED`	The PAT was replaced, but cached credentials could not be cleared.	Read the new PAT from `/system/brains-list`, check cache health, then rotate again.

A 503 with BRAIN_PAT_CACHE_INVALIDATION_FAILED means the new PAT is already saved. Do not assume the old PAT is rejected everywhere until the cache is cleared.

The BrainAPI dashboard calls this endpoint when you choose Replace access key on a brain's Connect page. The dashboard only offers it when the brain's software version supports it.

Clear or delete a brain

Use the system PAT for these destructive operations. Stop active imports and take a backup first if you need to retain the data.

Request	Effect
`POST /system/brains/{brain_id}/clear`	Removes the brain's data and keeps its ID and PAT.
`DELETE /system/brains/{brain_id}`	Removes the data, registered brain identity, PAT, and cached credentials.

A 409 means another lifecycle operation is running. A 503 with BRAIN_CLEANUP_FAILED lists the failed backends. Check their health, then retry the same operation. Clearing an unknown brain returns 404.

Failure behavior

Status	Meaning	Check
`400`	Brain ID is missing, malformed, or reserved.	Header spelling and ID characters.
`401`	PAT is missing, malformed, or does not match the brain.	Token source and selected brain.
`406`	Brain does not exist and automatic creation/fallback did not resolve it.	Brain creation settings or administrative creation.
`503`	Brain lookup could not reach MongoDB.	MongoDB connection and credentials.

Security guidance

Keep the system token in trusted operator services; give applications brain-scoped PATs.
Never put PATs in URLs, examples committed to source, browser logs, or analytics.
Validate the caller's tenant-to-brain mapping before forwarding X-Brain-ID.
Rotate a leaked PAT and clear any intermediary cache that stored it.

See Errors and HTTP statuses for cross-API behavior.

BrainAPI Authentication and Brains

On this page