Console Auth Flow

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

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

Logging in and using the result:

# Authenticate; both cookies come back on this response
curl --request POST "https://console.stateset.com/api/auth/login" \
  --header "Content-Type: application/json" \
  --cookie-jar cookies.txt \
  --data '{ "email": "[e-mail]", "password": "..." }'

# Any protected route needs the jar, not an Authorization header
curl "https://console.stateset.com/api/auth/me" --cookie cookies.txt

Response

{
  "user": { "id": "usr_4471", "email": "[e-mail]" },
  "org": { "id": "org_88", "name": "Example Inc" }
}

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.

Next steps

Console overview

What the console does with the session established here.

Agent pipeline

Where the orgId check is enforced.

Console mobile

The same auth, on a device that stores tokens differently.

Sandbox API

What sandbox_session grants access to.