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.
This feature is implemented with the @kit/auth package and the Supabase Auth features.
When To Use
- Starting from
apps/mobiletemplate 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/dashboardAPI running for user bootstrap.
Google sign-in package (@react-native-google-signin/google-signin) requires native build tooling and does not run in Expo Go.
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 = trueEnable password provider in apps/mobile/config/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.
Local Supabase exposes an inbucket inbox at http://localhost:54324.
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.
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.
| Filter | Parameters | Return | Registered By (package file) | Initialized In (app entrypoint) | Environment |
|---|---|---|---|---|---|
get_translations | { language: string; namespace: string } | Record<string, string> | null | kit/auth/src/native/filters/use-filters/use-translation-filters.tsx | apps/mobile/hooks/use-filters.ts (useAuthFilters) | client |
- Keep
useAuthFilters()inapps/mobile/hooks/use-filters.ts. - Keep
applyAsyncFilter('get_translations', ...)inapps/mobile/config/i18n.config.ts.
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
- Configure enabled providers in
supabase/config.toml. - Mirror providers and URLs in
apps/mobile/config/auth.config.ts. - 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.
Related
Fastest path from clone to running the mobile app with dashboard API and local Supabase.
Implement @kit/auth native flows in a custom Expo app using the apps/mobile architecture.
How is this guide?
Last updated on 3/27/2026