Authentication
Better Auth running inside Convex, the web app's proxy, sessions, and OAuth for MCP clients.
Sign-in is Better Auth, running inside Convex
through the @convex-dev/better-auth component. Its tables live in the
betterAuth component, and its HTTP routes are mounted by convex/http.ts.
Sign-in methods
Configured in packages/backend/convex/auth.ts:
- Email one-time codes (the
emailOTPplugin): 6 digits, valid for 5 minutes.convex/email.tssends them with Resend's HTTP API whenRESEND_API_KEYis set, and otherwise logs them. - Google, enabled only when both
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETare set. Account linking is on, so Google and an email code for the same verified address are one account.
The convex plugin issues the Convex JWTs that convex/auth.config.ts
lets Convex verify, which is what makes ctx.auth.getUserIdentity() work.
The web side
| File | Role |
|---|---|
apps/web/src/app/api/auth/[...all]/route.ts | Forwards /api/auth/* to Convex, so auth cookies are first-party |
apps/web/src/server/auth.server.ts | Next.js adapter: handler, getToken, fetchAuthQuery, and the per-request getAuthSession() |
apps/web/src/lib/auth-client.ts | The browser client and the sign-in actions |
The root layout reads the session on the server and hands it to
<Providers>, so client components read the user with useSession().
Layouts don't re-render on client navigation, so:
- signing in pushes to
/dashboardand then callsrouter.refresh(); - signing out does a full page load to
/, so nothing of the account stays in memory; - anything else that changes who's signed in or their profile calls
router.refresh().
The (app) route group's layout redirects signed-out visitors to /.
The Android app
The app in apps/mobile signs in with the same accounts through
@better-auth/expo:
the expo() server plugin in convex/auth.ts, and expoClient in
apps/mobile/src/lib/auth-client.ts.
- The app has no browser origin, so it sends its deep-link URL in an
expo-originheader, which the plugin uses as the origin.settlr://(the app's scheme) is always trusted; Expo Go'sexp://only whereTRUSTED_ORIGINSlists it. - The session cookie is kept in the phone's secure storage
(
expo-secure-store) and sent as aCookieheader, so people stay signed in across restarts. - Google opens in an in-app browser through
/expo-authorization-proxy, which sets the OAuth state cookie, and comes back to the app's deep link with the session in the URL. Google returns toSITE_URL, so the state cookie has to be set there: the app talks toEXPO_PUBLIC_SITE_URL(the web app, whose/api/auth/*route forwards to Convex), not to the.convex.siteURL. ConvexBetterAuthProviderfrom@convex-dev/better-auth/reactswaps the session for a Convex JWT, as on the web.
Allowed origins
Better Auth's base URL is the deployment's SITE_URL. Other origins that may
sign in go in TRUSTED_ORIGINS (comma-separated). On a dev deployment whose
SITE_URL is a hosted site, adding http://localhost:3000 there lets you
sign in locally with email codes; Google always returns to SITE_URL. Add
exp:// to sign in from Expo Go (the dev deployment has
http://localhost:3000,exp://).
OAuth for MCP clients
AI apps connect through Better Auth's mcp plugin plus Settlr's own
mcpBridge plugin:
The client reads the metadata at /.well-known/oauth-protected-resource
and /.well-known/oauth-authorization-server (served by the web app,
proxied from Better Auth) and registers itself dynamically.
It sends the user to /mcp/authorize. mcpBridge redirects signed-out
users to /connect to sign in, and always forces a consent step
(prompt=consent): anyone can register a client, so every authorization
is approved by the user on /connect. It also keeps only known scopes
and adds offline_access, so the client gets a refresh token.
The client trades the code at /mcp/token (PKCE is required).
mcpBridge rejects codes that haven't been approved yet, and after a
refresh it deletes the old token pair, so refresh tokens are single-use.
Refresh tokens last 30 days.
For each MCP request, the web app's /api/mcp route swaps the bearer
access token for a Convex JWT at /api/auth/mcp/convex-token, then calls
Convex as that user.
Upgrading better-auth
The token exchange calls the Convex plugin's getToken endpoint with a
stand-in session, which leans on Better Auth internals: recheck it when
upgrading. better-auth is pinned to the exact version
@convex-dev/better-auth is built against (1.6.15); upgrade the two
together.
The OAuth issuer is SITE_URL, so test MCP clients against that origin.