Features
PreviousNext

Authentication

Configure native authentication flows for apps/mobile using @kit/auth and Supabase Auth.

What It Does

This page covers the baseline mobile auth setup:

  • provider configuration in Supabase,
  • native auth config in apps/mobile/config/auth.config.ts,
  • and route protection in apps/mobile/app/(app)/_layout.tsx.

When To Use

  • Starting from apps/mobile template auth setup.
  • Porting the same auth architecture to another Expo app.
  • Enabling or switching providers (password, google, etc.).

Prerequisites

  • Supabase project configured locally (pnpm run supabase:start) or remotely.
  • Mobile env values configured in apps/mobile/.env.local.
  • apps/dashboard API running for user bootstrap.

Password

Enable email/password in supabase/config.toml.

To enable the email provider, ensure auth.email is configured.

[auth.email]
# Allow/disallow new user signups via email to your project.
enable_signup = true
# If enabled, a user will be required to confirm any email change on both the old, and new email
# addresses. If disabled, only the new email is required to confirm.
double_confirm_changes = true
# If enabled, users need to confirm their email address before signing in.
enable_confirmations = true

Enable password provider in apps/mobile/config/auth.config.ts.

auth.config.ts
import { parseAuthConfig } from '@kit/auth/config'; import { envs } from '~/envs'; const urls = { exit: '/', dashboard: '/', callback: '/auth/callback', signIn: '/auth/sign-in', signUp: '/auth/sign-up', forgottenPassword: '/auth/forgotten-password', verifyMfa: '/auth/verify', contactPage: `${envs().EXPO_PUBLIC_MARKETING_URL}/en/contact`, privacyPolicy: `${envs().EXPO_PUBLIC_MARKETING_URL}/en/privacy-policy`, termsOfUse: `${envs().EXPO_PUBLIC_MARKETING_URL}/en/terms-of-use`, } satisfies Record<string, string>; export const authConfig = parseAuthConfig({ environment: 'native', urls, // whether to display the terms checkbox during sign-up displayTermsCheckbox: true, // NB: Enable the providers below in the Supabase Console // in your production project providers: { password: true, }, passwordRequirements: { minLength: 3, maxLength: 99, specialChars: false, numbers: false, uppercase: false, }, });

Protect signed-in routes with AuthProvider in app/(app)/_layout.tsx.

Authentication Emails

Password flows need email delivery for signup confirmations and recovery links.

OAuth Providers

Enable provider in Supabase (example: Google).

[auth.external.google]
enabled = true
client_id = "env(SUPABASE_AUTH_EXTERNAL_GOOGLE_CLIENT_ID)"
secret = "env(SUPABASE_AUTH_EXTERNAL_GOOGLE_SECRET)"
redirect_uri = "env(SUPABASE_AUTH_EXTERNAL_REDIRECT_URI)"

Enable OAuth provider in auth.config.ts.

apps/mobile/config/auth.config.ts
providers: {
  password: true,
  oAuth: ['google'],
},

Set required mobile env variables.

EXPO_PUBLIC_SUPABASE_GOOGLE_CLIENT_ID="your-google-client-id"
EXPO_PUBLIC_IOS_URL_SCHEMA="your-ios-url-schema"

Filter API

Mobile auth package integrations are filter-based for translations and feature composition inside the app runtime.

FilterParametersReturnRegistered By (package file)Initialized In (app entrypoint)Environment
get_translations{ language: string; namespace: string }Record<string, string> | nullkit/auth/src/native/filters/use-filters/use-translation-filters.tsxapps/mobile/hooks/use-filters.ts (useAuthFilters)client

MCP Context

capability: auth_mobile_setup entrypoints: - apps/mobile/config/auth.config.ts - apps/mobile/app/(app)/_layout.tsx - apps/mobile/hooks/use-filters.ts - apps/mobile/config/i18n.config.ts - kit/auth/src/native/filters/use-filters/use-translation-filters.tsx - supabase/config.toml inputs: - auth_provider_selection - supabase_provider_credentials outputs: - native_authentication_flow constraints: - provider config must match supabase enabled providers - apps/dashboard API must be reachable for db user bootstrap side_effects: - user session creation and refresh

Agent Recipe

  1. Configure enabled providers in supabase/config.toml.
  2. Mirror providers and URLs in apps/mobile/config/auth.config.ts.
  3. Validate auth redirects and protected routes in app/(app)/_layout.tsx.

Troubleshooting

  • If sign-in succeeds but app loops to auth screens, verify db user fetch in clientTrpc.getUser.
  • If OAuth fails on device, verify redirect URI and iOS URL schema values.
  • If confirmation emails are missing in local setup, check inbucket on localhost:54324.

How is this guide?

Last updated on 3/27/2026