Auth and identity
Sessions, API keys, handoff, and MCP authorization.
CognitiveX has two authentication paths.
Browser sessions
Web users sign in through /api/auth/signin or OAuth. The API returns an access
token and sets an HttpOnly refresh_token cookie scoped to /api/auth.
Production can set COOKIE_DOMAIN to the parent domain so the same session can
move between product subdomains.
Browser apps call /api/auth/refresh on boot. The shared API client stores the
short-lived access token in memory and retries one failed request after refresh.
API keys
Programmatic clients create personal API keys with POST /api/auth/api-keys.
The returned key starts with icog_ and is shown only once. The server stores a
SHA-256 hash and a short prefix for display and logs.
Use either header form:
X-API-Key: icog_...Authorization: Bearer icog_...icog/dependencies.py resolves both forms, binds the request user, and marks
request logs with client_label=api-key.
MCP authorization
The hosted MCP endpoint supports bearer API keys directly and also exposes an
OAuth 2.0 + PKCE flow for MCP clients that discover
/.well-known/oauth-authorization-server.
The MCP OAuth flow registers an ephemeral client, opens an iCog consent page, then exchanges an authorization code for an iCog API key. That key is what the MCP middleware uses to scope tool calls to the authenticated user.
Identity continuity
Identity state is exposed through /api/identity/*. The identity routes let a
user inspect the kernel, confirm or correct anchors, forget identity records,
resolve conflicts, and review audit log entries.
Use identity endpoints for facts that shape the user's continuity across sessions. Use ordinary memory endpoints for project notes, events, preferences, and procedural knowledge.