> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchtoday.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Backend Authentication Setup

> Configure Better Auth on the API backend for secure authentication

## Overview

The Launch API backend uses [Better Auth](https://better-auth.com) 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.

* [Apple Sign-In (iOS)](/authentication/apple-signin)
* [Google Sign-In (Android)](/authentication/google-signin)