Configuration

TurboStarter supports multiple authentication methods on mobile:

Password - the traditional email/password method
Magic Link - passwordless email link authentication
OTP - one-time passwords sent to email or phone
Anonymous - guest mode for unauthenticated users
OAuth - OAuth providers; Apple, Google, and GitHub are set up by default

All methods are enabled by default; you can enable, disable, or configure any of them to your needs.

You can mix and match these methods or add new ones - for example, password and magic link at the same time - so users have flexibility in how they sign in.

Authentication configuration can be customized through a simple configuration file. The following sections explain the available options and how to configure each authentication method based on your requirements.

API

To enable a new authentication method or add a plugin, update the shared API configuration. See web authentication configuration for details; the server setup is shared between web and mobile.

Remember to add your app scheme as trusted origin

For mobile apps, we need to define an authentication trusted origin using a mobile app scheme instead.

App schemes (like turbostarter://) are used for deep linking users to specific screens in your app after authentication.

To find your app scheme, take a look at apps/mobile/app.config.ts file and then add it to your auth server configuration:

server.ts

export const auth = betterAuth({
  ...

  trustedOrigins: ["turbostarter://**"],

  ...
});

Adding your app scheme to trusted origins is required for security - it prevents CSRF and open redirects by allowing only requests from your app.

UI

Separate configuration controls what is shown in the UI. It lives in apps/mobile/config/auth.ts.

apps/mobile/config/auth.ts

import { Platform } from "react-native";

import { authConfigSchema, type AuthConfig } from "@workspace/auth";

export const authConfig = authConfigSchema.parse({
  providers: {
    password: true,
    emailOtp: false,
    magicLink: false,
    anonymous: true,
    oAuth: [
      Platform.select({
        android: "google",
        ios: "apple",
      }),
      "github",
    ],
  },
}) satisfies AuthConfig;

The configuration is validated with a Zod schema, so invalid values surface as errors at startup.

Use environment variables instead of inline configuration

Avoid editing the config file directly. Prefer environment variables to override the defaults.

For example, to switch from password to magic link, set:

.env.local

EXPO_PUBLIC_AUTH_PASSWORD=false
EXPO_PUBLIC_AUTH_MAGIC_LINK=true

To show third-party providers in the UI, add the provider to the oAuth array. Defaults: Google and GitHub (with platform-specific Apple on iOS).

apps/mobile/config/auth.ts

providers: {
    ...
    oAuth: [
      Platform.select({
        android: SocialProvider.GOOGLE,
        ios: SocialProvider.APPLE,
      }),
      SocialProvider.GITHUB,
    ],
    ...
},

You can even display specific providers for specific platforms - for example, you can display Google authentication for Android and Apple authentication for iOS.

Third-party providers

To enable third-party authentication providers, you'll need to:

Create an OAuth application in the provider’s developer console (Apple, Google Cloud Console, GitHub, or another supported provider).
Set the matching environment variables in your TurboStarter API (shared with web).

Each provider needs its own credentials and environment variables. See the Better Auth OAuth docs for step-by-step setup per provider.

Multiple environments

Make sure to set both development and production environment variables appropriately. Your OAuth provider may require different callback URLs for each environment.

API

UI

Third-party providers

On this page