Skip to main content

​
Overview

The Launch API backend uses Better Auth to handle authentication for both the server and the mobile client. It provides a unified flow for sessions, social sign-in, and account management, so the API and app stay in sync.

​
How It Works (High Level)

Better Auth runs in the API and exposes authentication endpoints that the mobile app calls. When a user signs in, the API issues a session and persists user data in the database. The mobile app then uses that session to access protected API routes.

​
What You Configure

You will set up:
  • A database connection (so auth can store users and sessions).
  • A strong auth secret (used to sign and validate sessions).
  • Optional provider credentials (Apple, Google, etc.) when you enable them.
  • Trusted origins for development and production.

​
What’s Required To Run Locally

At minimum, the API needs a database URL and a Better Auth secret to boot. Other provider values can stay unset until you start integrating those features.

​
Server-Side Authentication Flow

The API wiring lives in a small set of files:
  • apps/api/src/services/auth.ts initializes Better Auth, enables Expo + email OTP plugins, and conditionally enables Apple/Google providers when their credentials exist. It also sets session lifetimes and cookie behavior and captures device metadata on sign-in.
  • apps/api/src/routes/auth/auth.ts bridges Koa requests to the Better Auth handler, logs auth requests safely, and stores device details on successful sign-in.
  • apps/api/src/services/device-middleware.ts writes device metadata to the session record, using the token returned by Better Auth.

​
Mobile Client Authentication Flow

On the client, authentication is structured around a dedicated auth client and screen-specific flows:
  • apps/mobile/lib/auth/client.ts creates the Better Auth client, sets the API base URL, adds Expo + email OTP plugins, and injects device headers on every auth call. It also stores auth data securely using Expo Secure Store.
  • apps/mobile/lib/auth/session-context.tsx provides a session context with a single fetch-on-mount flow, plus refetch and clearSession helpers.
  • apps/mobile/app/auth/login.tsx drives Apple/Google sign-in and refreshes the session after successful auth.
  • apps/mobile/app/auth/email-signin.tsx requests an email OTP.
  • apps/mobile/app/auth/verify-email-otp.tsx verifies the OTP and refreshes the session on success.
  • apps/mobile/lib/auth/google.ts handles Google OAuth via Expo Auth Session, does the code exchange, and returns an ID token that Better Auth can validate.
  • apps/mobile/lib/trpc/client.ts attaches Better Auth cookies to API requests so authenticated calls work with tRPC.

​
Next Steps

Start with Apple Sign-In if you are shipping iOS. If you’re focused on Android first, skip ahead to Google Sign-In and come back to Apple later.