Mobile Authentication

Overview

The Launch mobile app uses Better Auth with Expo integration for a secure, seamless authentication experience. This guide explains how authentication works in the mobile client and how it connects to the API.

Prerequisites

Backend running with auth routes enabled
EXPO_PUBLIC_API_URL set in apps/mobile/.env (from apps/mobile/example.env)

Steps

Configure auth providers in the API: Backend Authentication Setup
Verify mobile auth screens in apps/mobile/app/auth
Test sign‑in on device or simulator

Architecture

Authentication Flow

Key Components

Auth Client

Location: apps/mobile/lib/auth/client.ts. Central authentication client that handles Better Auth requests, secure storage, and device headers.

Route Protection

Location: app/_layout.tsx and lib/hooks/useAppNavigation.ts. Navigation guards redirect users based on session and onboarding state.

Device Tracking

Location: apps/mobile/lib/utils/device-info.ts. Captures device information for security and analytics purposes.

Implementation Details

1. Auth Client Setup

The authentication client is configured in lib/auth/client.ts:

export const authClient = createAuthClient({
  // IMPORTANT: For mobile OAuth (Google), this must be reachable from your device.
  // Use your ngrok HTTPS URL during development (recommended).
  baseURL: `${process.env.EXPO_PUBLIC_API_URL}/api/auth`,
  plugins: [
    expoClient({
      scheme: "launch", // Deep link scheme
      storagePrefix: "launch", // SecureStore prefix
      storage: SecureStore, // Native secure storage
    }),
  ],
  fetchOptions: {
    customFetchImpl: async (url, init) => {
      const deviceHeaders = getDeviceHeaders();
      // Automatically inject device info in all requests
      return fetch(url, {
        ...init,
        headers: { ...init?.headers, ...deviceHeaders },
        credentials: "omit",
      });
    },
  },
});

Key Features:

Secure Storage: Uses Expo SecureStore for session persistence
Device Headers: Automatically includes device information in all requests
Deep Linking: Handles OAuth callbacks via launch:// scheme
Type Safety: Full TypeScript support with session hooks

Google OAuth (Android) requires a single origin.If your API is exposed via ngrok (e.g. https://xxxx.ngrok-free.app), then:

BETTER_AUTH_URL (API) must use that same origin
EXPO_PUBLIC_API_URL (mobile) must also use that same origin

If mobile starts auth at http://192.168.x.x:3001 but the callback returns to https://xxxx.ngrok-free.app, you will get a state mismatch error.

2. Route Protection

Authentication state determines which screens users can access. The current implementation handles redirects in useAppNavigation.ts and keeps the route stack defined in app/_layout.tsx. Benefits:

Centralized: Redirect rules live in one hook
Automatic: Users are routed based on auth and onboarding state
Type Safe: Expo Router provides full TypeScript support

3. Session Management

Sessions are managed by a lightweight provider that calls Better Auth to fetch the current session on app start and after auth events:

Persistence: Sessions survive app restarts via SecureStore
Manual refresh: SessionProvider calls authClient.getSession() on mount and exposes a refetch() helper used after sign-in/sign-out
Navigation: useAppNavigation derives the auth/onboarding target route

4. Device Information Tracking

Every authentication request includes device metadata:

export const getDeviceHeaders = (): Record<string, string> => {
  const deviceInfo = getDeviceInfo();

  return {
    "X-Device-Name": deviceInfo.deviceName || "unknown",
    "X-Device-Model": deviceInfo.deviceModel || "unknown",
    "X-OS-Version": deviceInfo.osVersion || "unknown",
    "X-App-Version": deviceInfo.appVersion || "unknown",
    "X-App-Platform": deviceInfo.platform,
    "X-Device-Type": deviceInfo.deviceType,
  };
};

Use Cases:

Security: Detect suspicious login patterns
Analytics: Understand user device distribution
Support: Debug issues specific to device types
Features: Enable/disable features based on device capabilities

Authentication Providers

Configured for iOS devices with automatic availability detection:

// Check if Apple Sign-In is available
const isAvailable = await AppleAuthentication.isAvailableAsync();

// Handle Apple authentication
await authClient.signIn.social({
  provider: "apple",
  idToken: {
    token: credential.identityToken,
    nonce,
  },
  callbackURL: "/",
});

Features:

Native UI: Uses Apple’s native sign-in button
Secure: Implements proper nonce generation for security
Graceful Fallback: Shows standard button when unavailable

Implemented via Better Auth’s Expo client. The login screen calls authClient.signIn.social({ provider: "google" }), which opens the OAuth flow in a browser and returns to the app via the launch:// scheme. Email OTP sign-in is wired end-to-end. The flow uses Better Auth’s email OTP plugin and a dedicated verification screen:

apps/mobile/app/auth/email-signin.tsx (send code)
apps/mobile/app/auth/verify-email-otp.tsx (enter code)
docs/authentication/email-signin.mdx (setup details)

Platform-specific Behavior

iOS

Apple Sign-In uses the native expo-apple-authentication flow to obtain an Apple identity token and then calls Better Auth signIn.social({ provider: "apple", idToken }).
Google Sign-In uses Better Auth’s Expo client for browser-based OAuth and deep links back to the app via the launch:// scheme.

Android

Google Sign-In uses the same Better Auth Expo client flow as iOS (browser OAuth + deep link). Ensure your auth flow starts and ends on the same origin to avoid state mismatch errors.
Apple Sign-In is not available on Android.

Security Notes

Sessions are stored in SecureStore, OAuth redirects use the launch:// scheme, and device metadata is attached to auth requests for tracing and support.

Next Steps

Apple Sign-In Setup
Google Sign-In Setup
Email Sign-In with OTP
CORS Protection: Configured trusted origins prevent unauthorized access
Request Signing: Device headers provide request authenticity
Rate Limiting: Backend prevents brute force attacks
Error Logging: Comprehensive error tracking for security monitoring

Usage Examples

Checking Authentication State

import { authClient } from "@/lib/auth-client";

function MyComponent() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return <LoadingSpinner />;

  if (session) {
    return <WelcomeMessage user={session.user} />;
  }

  return <LoginPrompt />;
}

Manual Sign Out

const handleSignOut = async () => {
  try {
    await authClient.signOut();
    // User automatically redirected to public routes
  } catch (error) {
    console.error("Sign out error:", error);
  }
};

Accessing User Data

const { data: session } = authClient.useSession();

if (session?.user) {
  const { name, email, image } = session.user;
  // Use user data in your components
}

Troubleshooting

Common Issues

Session not persisting across app restarts

Cause: SecureStore permissions or configuration issueSolution:

Check that expo-secure-store is properly installed
Verify the storage prefix matches your app configuration
Test on a physical device (simulator may have limitations)

Auth state not updating UI

Cause: Component not subscribed to auth state changesSolution:

Use authClient.useSession() hook in your components
Ensure components are wrapped in proper providers
Check that React Query is configured correctly

Debug Mode

Enable detailed auth logging by setting:

// In development
if (__DEV__) {
  console.log("Auth Debug Mode Enabled");
  // Additional logging will appear in console
}

Environment Variables

The following environment variables are required in your API backend:

# Better Auth Configuration
BETTER_AUTH_SECRET=your-secret-key
BETTER_AUTH_URL=http://localhost:3001

# Apple Sign-In (iOS)
APPLE_CLIENT_ID=your.app.bundle.id
APPLE_TEAM_ID=YOUR_TEAM_ID
APPLE_KEY_ID=YOUR_KEY_ID
APPLE_PRIVATE_KEY_BASE64=base64_encoded_private_key

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/launch

Next Steps

See the Environment Setup Guide for complete configuration details.

Next Steps

Environment Setup - Configure your development environment
File Structure - Understand the mobile app organization

​Overview

​Prerequisites

​Steps

​Architecture

​Authentication Flow

​Key Components

Auth Client

Route Protection

Device Tracking

​Implementation Details

​1. Auth Client Setup

​2. Route Protection

​3. Session Management

​4. Device Information Tracking

​Authentication Providers

​Apple Sign-In

​Google Sign-In

​Email Sign-In (OTP)

​Platform-specific Behavior

​iOS

​Android

​Security Notes

​Next Steps

​Usage Examples

​Checking Authentication State

​Manual Sign Out

​Accessing User Data

​Troubleshooting

​Common Issues

​Debug Mode

​Environment Variables

​Next Steps

​Next Steps

Overview

Prerequisites

Steps

Architecture

Authentication Flow

Key Components

Implementation Details

1. Auth Client Setup

2. Route Protection

3. Session Management

4. Device Information Tracking

Authentication Providers

Apple Sign-In

Google Sign-In

Email Sign-In (OTP)

Platform-specific Behavior

iOS

Android

Security Notes

Next Steps

Usage Examples

Checking Authentication State

Manual Sign Out

Accessing User Data

Troubleshooting

Common Issues

Debug Mode

Environment Variables

Next Steps

Next Steps