Soar API Setup

This is the Unified Mode counterpart to Supabase Setup: everything needed to run the desktop app against a conforming Web host instead of a Supabase project. If you haven't picked a mode yet, start at Backend Modes.

No host is privileged by framework name — Next.js, Nuxt, and TanStack Start all work; conformance to the frozen contracts is the compatibility boundary.

1. Deploy a conforming host

Deploy one of the Web templates as a Unified Platform Host and complete its host-side setup (database, Better Auth URL and secret, App API):

• Next.js App API
• Nuxt App API
• TanStack Start App API

Sign up on the Web and verify /api/auth/get-session works before touching the desktop side. For the cross-template picture, see the platform Unified Quick Start.

2. Configure the client build

Unified Mode needs two environment values at build time:

# .env
SOAR_BACKEND_MODE=soarApi

# Service root of the host deployment; http://localhost:3000 works for a
# local dev host. Consumed by the MAIN process only — never the renderer.
SOAR_API_BASE_URL=https://your-web-app.example.com

The SUPABASE_* keys can stay unset — the Supabase backend graph is never imported in this mode. The request Origin is the fixed desktop scheme soar://.

3. Configure the host for this app

On the server (the selected host's deployment environment), the app expects the native support described in Native Authentication:

Electron Unified intentionally does not implement OAuth, device tokens, or test push — those capabilities are absent rather than silently approximated, so no OAuth audiences or push credentials are required for desktop.

4. Sessions live in an encrypted main-process store

In Unified Mode the app authenticates with Better Auth Bearer tokens (the set-auth-token response header), not cookies:

• The token is persisted only in a safeStorage-encrypted store owned by the main process, namespaced by app ID, API origin, and build channel — a development session is never restored by a production build.
• The renderer receives a sanitized session over typed IPC; the Bearer token, Authorization header, and presigned URLs never cross the IPC boundary.
• On relaunch the stored session is restored and validated against the server; sign-out clears both the stored token and in-memory state.
• Sessions are database-backed and revocable: revoking a session on the web invalidates the desktop token immediately, and the app treats 401 as "sign in again" — it never retry-loops and never falls back to Supabase auth.

5. Billing through the host

Desktop billing follows the host's subscription state: the app reads the shared subscription snapshot, and checkout or portal flows open provider URLs issued by the host. The main process validates those URLs before opening them externally.

Verify the setup

Run the shared smoke test across both surfaces:

• Sign up or sign in on desktop (email/OTP), then open the same account on the Web.
• Update the profile on one surface and read it from the other.
• Create, edit, reorder, and delete a todo across both surfaces.
• Upload an avatar and confirm its completion URL is readable.
• Revoke the desktop session from the Web and verify the app returns to sign-in.
• Complete a test checkout from desktop and confirm the same entitlement appears on both surfaces.
• Delete the account from desktop and confirm the cascade on the host.

For a concrete end-to-end walkthrough of one host-and-client pair, follow Next.js + Swift Unified Setup — the steps map onto desktop, minus OAuth and push.

Related pages