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 #
{
"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).
{"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.
{
"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.