Console Auth Flow

Four auth modes, three cookies, and what each one grants.

Console Auth Flow

The console supports several auth modes and issues a signed session cookie for protected routes.

Modes

Mode	How it works
Email / password	Proxied to the Sandbox API login
API key	Validated locally in the console
Token refresh	Re-issues a session from an existing JWT
Dev login	Optional, non-production only

Dev login exists to skip authentication during development. Confirm it is disabled in any environment reachable from outside your machine — it is the one mode that bypasses credential checks entirely.

Cookies

Three cookies, with different scopes — worth understanding separately because they fail differently:

Cookie	Contains	Grants
session	Signed JWT with orgId and userId	Access to console routes
sandbox_session	Sandbox token	Calls to the Sandbox API
api_key	Stored API key	API-key auth mode

session and sandbox_session can expire independently. A user with a valid session but a stale sandbox_session reaches the console fine and then fails on anything that executes — which presents as an agent error rather than an auth error. Check both when diagnosing.

The flow

POST /api/auth/login
      │
      ├─ email/password ──▶ Sandbox API validates
      └─ api key        ──▶ console validates locally
      │
      ▼
 set session + sandbox_session cookies
      │
      ▼
 return user and org metadata

Routes

Route	Purpose
POST /api/auth/login	Authenticate
POST /api/auth/logout	Clear session
GET /api/auth/me	Current user and org
POST /api/auth/refresh	Re-issue a session
POST /api/auth/register	Create an account
POST /api/auth/forgot-password · /reset-password	Recovery
POST /api/auth/resend-verification	Re-send verification

Org scoping

The session JWT carries orgId, and downstream handlers check ownership against it — see verify chat ownership in the agent pipeline. Authentication establishes who; the orgId check establishes whose data.

Related

• Console Overview
• Console Agent Pipeline
• Console Mobile