> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**        |

<Warning>
  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.
</Warning>

## 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        |

<Note>
  `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.
</Note>

## 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](/stateset-console/stateset-console-agent-pipeline#the-pipeline) in the agent
pipeline. Authentication establishes *who*; the `orgId` check establishes *whose data*.

## Related

* [Console Overview](/stateset-console/stateset-console-overview)
* [Console Agent Pipeline](/stateset-console/stateset-console-agent-pipeline)
* [Console Mobile](/stateset-console/stateset-console-mobile)