docs/security/credentials.md

Administrator, access tokens, and browser sessions

SYSTEM_PAT is the single deployment administrator. A legacy BRAINPAT_TOKEN may temporarily alias it; different values fail startup with SYSTEM_PAT_CONFLICT. Missing production credentials and the old default credential fail closed. Rotate any administrator credential previously shared in chat or exposed in logs.

Brains and Workspaces are resources and contain no new credentials. Administrators issue named scoped credentials through POST /system/access-tokens. Copy the one-time response securely, then use Authorization: Bearer (or compatibility BrainPAT) against the discovered workspace API/Agent/MCP endpoint. Listings contain metadata only. Revocation and expiry also invalidate derived sessions. Deleting/recreating a brain does not reactivate an old token for that name.

Existing Brain PATs temporarily authenticate only their own resource. Run python -m scripts.migrate_legacy_credentials to report migration status without printing secrets. For PostgreSQL, --migrate BRAIN_ID atomically moves a legacy secret into the hash-only registry and removes the plaintext Brain representations. This preserves the existing agent credential; it does not rotate an exposed secret. Issue a new named token, update its agents, then revoke the migrated token via DELETE /system/access-tokens/{id}. Do not automate rotation or deletion of legitimate production credentials. Mongo legacy PATs require operator-managed rotation; the atomic PostgreSQL migration tool intentionally refuses that backend.

The console exchanges its submitted access token for an opaque Redis session. Cookies are HttpOnly, Secure, SameSite=Strict, host-only, and expire after eight hours by default (CONSOLE_SESSION_TTL_SECONDS, bounded to 5 minutes–24 hours). Use HTTPS for browser access, including local integration. Cookie-authenticated mutations require the session CSRF value in X-CSRF-Token. Direct token requests do not use CSRF. Session and OAuth records retain principal references, never the submitted administrator or workspace token. OAuth sessions from older releases must be reauthorized because their plaintext credential mapping is no longer read.

Canonical routes are POST /system/brains, POST /system/workspaces, GET /brains/{slug}/agent/capabilities, and the workspace Native/Agent OpenAPI URLs. /meta/login-info is deprecated; use /auth/me. Do not guess /brains, /agent/capabilities, or workspace /api/meta/login-info aliases.

Runtime release gates

The default trace sink is TRACE_MODE=log; disabled disables traces and queue is an explicit opt-in for a consumer. Queue saturation is bounded and warnings are limited to once per minute with an accumulated drop count. The HF monitor checks configured PostgreSQL, Redis, and Ollama only. Logs and trace payloads use shared credential/header/URL redaction.

/health exposes persistence.mode, root, and production_ready. A durable root is an operator-provided persistent mount (/data by default, or BRAINAPI_DURABLE_ROOT). Merely creating a directory on ephemeral storage does not make it durable: operators must attach an actual durable volume. With no root, production startup requires ALLOW_EPHEMERAL_STORAGE=true for staging or recovery; this override never grants production GO. An explicitly configured PERSISTENCE_MODE must agree with detection.

New PostgreSQL clusters use UTF-8 and SCRAM host authentication with local peer authentication. Existing clusters are retained unchanged; audit/upgrade their encoding and authentication separately without destructive initialization. The Celery worker runs as appuser. MCP 1.28's upstream Settings.lifespan forward reference is rebuilt after importing FastMCP; no warning suppression is installed. The existing Starlette httpx TestClient deprecation is unrelated and remains visible in test results.