# Session API Two public read endpoints tell a client who is signed in and whether the session is still usable; a third publishes the account-creation catalog. They are what the Solid app bootstraps from. The server-rendered shell also carries display-only session attributes (`user-did`, `user-handle`, `user-display`, `user-avatar`, `is-moderator`, `unread-notifications`, `temperature-unit`), so the first paint does not flash a signed-out header while the client waits for `/api/session`. ## `GET /api/session` Public. Never answers `401`: an anonymous client gets an explicit unauthenticated body so a client-rendered shell can render signed-out without an error path (`HandleSessionJSON` in `internal/handlers/session_json.go`). ### Response ```json { "did": "did:plc:abc123", "handle": "alice.test", "display_name": "Alice", "avatar": "https://cdn.bsky.app/...", "is_authenticated": true, "is_moderator": false, "unread_notifications": 3, "user_preferences": {"temperature_unit": "recorded"}, "app": "oolong" } ``` | Field | Type | Description | |-------|------|-------------| | `did` | `string` | Viewer DID; `""` when anonymous. | | `handle` | `string` | Viewer handle; `""` when unknown or anonymous. | | `display_name` | `string` | Viewer display name; `""` when unset. | | `avatar` | `string` | Avatar URL; `""` when unset. | | `is_authenticated` | `bool` | Whether the request carried a resumable session. | | `is_moderator` | `bool` | Whether the viewer holds any moderation role. | | `unread_notifications` | `int` | Unread count from the feed index; `0` without one. | | `user_preferences` | `object` | Account preferences, always defaulted (see below). | | `app` | `string` | Product identifier (`"oolong"`), so a client can confirm which app answered. | `user_preferences.temperature_unit` is one of `recorded` (default), `celsius`, `fahrenheit`. Unknown stored values fall back to `recorded` (`UserPreferences.WithDefaults` in `internal/profileprefs`). This endpoint reports the preference; it does not convert any numbers for you — record values in the JSON API are always in the unit they were recorded in, and formatting is the client's job (`web/src/lib/format.ts` holds the Solid app's helpers). Identity fields come from the profile cache. A cache/PDS miss yields empty strings rather than an error, so `is_authenticated: true` with empty `handle`/`display_name` is valid — render the DID, then retry later. `Cache-Control: no-store`. Each call also loads the viewer context (unread count, preferences, profile), so a client that needs the count refreshes this endpoint rather than expecting it in other payloads. ## `GET /api/session/status` Public. Cheap proactive check for clients that want to prompt re-authentication *before* a save fails (`HandleSessionStatusJSON` in `internal/handlers/session_json.go`). ```json {"is_authenticated": true, "session_expired": false} ``` | Field | Type | Description | |-------|------|-------------| | `is_authenticated` | `bool` | Same meaning as on `/api/session`. | | `session_expired` | `bool` | Both auth cookies are present, but the session can no longer be resumed locally. | This is a best-effort local check: it catches sessions deleted locally (logout elsewhere, store cleared, cookies pointing at a missing row). It does **not** detect a refresh token revoked server-side — that only appears on the next PDS operation. The reactive path stays authoritative: every authenticated endpoint answers `401 authentication_required` when the session is gone. ## `GET /api/signup/providers` Public. Publishes the PDS hosting catalog the account-creation page offers, so that form can render before anyone is signed in. ```json { "categories": [ { "title": "Hosted PDS", "description": "...", "providers": [ { "url": "https://pds.example.com", "name": "Example PDS", "domain": "example.com", "description": "...", "location": "...", "badge": "...", "badge_color": "...", "operator_name": "...", "operator_url": "...", "signup_url": "https://example.com/signup" } ], "dev_only": false } ], "dev_mode": false } ``` | Field | Type | Description | |-------|------|-------------| | `categories` | `array` | Provider groups; dev-only groups are omitted unless the server runs in dev mode. | | `categories[].title`, `description` | `string` | Group heading and explanation. | | `categories[].providers` | `array` | Options for the signup picker. Optional provider metadata is an empty string rather than a missing key, so the shape does not change between providers. | | `categories[].dev_only`, `dev_mode` | `bool` | Whether the group or the catalog is development-only. | `POST /join/create` takes the chosen provider's `url` as `pds_url` and rejects anything the catalog does not list (`400 invalid_request`). ## Error codes seen by clients | Status | Code | When | |--------|------|------| | 401 | `authentication_required` | Authenticated endpoint without a usable session (or an expired one discovered mid-request). | | 401 | `session_expired` | Only `POST /api/settings/bluesky-profile` uses this code for an unreadable session; everywhere else it is `authentication_required`. | ## Browser auth flows (not JSON) | Method | Path | Behaviour | |--------|------|-----------| | GET | `/login?return=...` | Login page; `return` is validated by `safeReturnPath` and must be a local path. | | POST | `/auth/login` | Form field `handle`; 302 to the PDS auth server and sets the return-path cookie. A JSON request gets JSON errors, but the handle is still read from the form (`HandleLoginSubmit` in `internal/handlers/auth.go`). | | GET | `/oauth/callback` | Completes the flow and sets the DID + session cookies. | | POST | `/logout` | 303 back to `/`, clears cookies. | | POST | `/reauth` | Clears the stale session and restarts login for the same handle. | | GET | `/join/create`, POST `/join/create` | Account creation (`prompt=create`). The POST accepts `pds_url` as a JSON body or a form field and 302s to the auth server. | Clients that render their own UI should navigate the browser to `/login` (and submit these forms as real form posts); they cannot finish OAuth from JSON.