Configuration

TurboStarter supports three different authentication methods:

Password - the traditional email/password method
Magic Link - passwordless email link authentication
OAuth - OAuth providers, Google and Github are set up by default

All authentication methods are enabled by default, but you can easily customize them to your needs. You can enable or disable any method, and configure them according to your requirements.

Remember that you can mix and match these methods or add new ones - for example, you can have both password and magic link authentication enabled at the same time, giving your users more flexibility in how they authenticate.

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 new authentication method or add some plugin, you'd need to update the API configuration. Please refer to web authentication configuration for more information as it's not strictly related with mobile app configuration.

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 the trusted origins list is crucial for security - it prevents CSRF attacks and blocks malicious open redirects by ensuring only requests from approved origins (your app) are allowed through.

UI

We have separate configuration that determines what is displayed to your users in the UI. It's set at apps/mobile/config/auth.ts.

The recommendation is to not update this directly - instead, please define the environment variables and override the default behavior.

apps/mobile/config/auth.ts

import { SOCIAL_PROVIDER, authConfigSchema } from "@turbostarter/auth";
 
import { env } from "~/lib/env";
 
import type { AuthConfig } from "@turbostarter/auth";
 
export const authConfig = authConfigSchema.parse({
  providers: {
    password: env.EXPO_PUBLIC_AUTH_PASSWORD,
    magicLink: env.EXPO_PUBLIC_AUTH_MAGIC_LINK,
    oAuth: [SOCIAL_PROVIDER.GOOGLE, SOCIAL_PROVIDER.GITHUB],
  },
}) satisfies AuthConfig;

The configuration is also validated using the Zod schema, so if something is off, you'll see the errors.

For example, if you want to switch from password to magic link, you'd set the following environment variables:

.env.local

EXPO_PUBLIC_AUTH_PASSWORD=false
EXPO_PUBLIC_AUTH_MAGIC_LINK=true

To display third-party providers in the UI, you need to set the oAuth array to include the provider you want to display. The default is Google and Github.

apps/web/config/auth.ts

providers: {
    ...
    oAuth: [SOCIAL_PROVIDER.GOOGLE, SOCIAL_PROVIDER.GITHUB],
    ...
},

Third party providers

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

Set up an OAuth application in the provider's developer console (like Google Cloud Console, Github Developer Settings or any other provider you want to use)
Configure the corresponding environment variables in your TurboStarter API (web) application

Each OAuth provider requires its own set of credentials and environment variables. Please refer to the Better Auth documentation for detailed setup instructions for each supported provider.

Environment variables

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