Tea journaling on ATProto (alpha) forked from arabica.social/arabica
oolong docs api session.md
6.4 kB · 142 lines
Markdown
at main

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.