Console session

Overview

When the Zero desktop app starts, it authenticates with the Zero console to retrieve the operator's plan, machine quota, and billing state. The session is maintained locally via a stored token that is refreshed automatically.

The /console/* routes are part of Zero's local API server. They proxy requests to the remote console using the locally cached session token. Operators interacting with the desktop app do not call these endpoints directly.

Sign in

Authenticate with the console using email and password. On success, the token is persisted locally and the current snapshot is returned.

POST /console/sign-in
{ "email": "you@example.com", "password": "..." }

→ 200 OK: console snapshot (plan, machines, connection)
→ 401 Unauthorized: invalid credentials
→ 503 Service Unavailable: console unreachable

Current user

Returns the current authenticated user record by refreshing the local cache from the console.

GET /console/me

→ 200 OK: snapshot
→ 401 Unauthorized: no valid session

Refresh session

Forces a cache refresh against the console. Useful after plan changes or machine updates.

POST /console/refresh

→ 200 OK: updated snapshot
→ 503: console unreachable

Connection state

Returns the current connection state as an enum string. The desktop app polls this to update its status indicator.

GET /console/connection

→ { "state": "CONNECTED" | "CONNECTING" | "STALE" | "DISCONNECTED" | "SIGNED_OUT" | "DEV_OVERRIDE" }

Connection states:

Sign out

Clears the local session token. The desktop app returns to SIGNED_OUT state.

POST /console/sign-out

→ { "ok": true }

API reference