The Complete Guide to Supabase Auth in React Native (email + Oauth + Apple Sign-

Your auth worked in Expo Go. You tapped Google, saw a success screen, got a user object back, and moved on. Then the actual app build landed on a device, the redirect stopped returning cleanly, the session vanished after backgrounding, and email verification dumped users into a browser with no way back into the app.

That gap is why most React Native auth guides feel complete but still leave production teams stuck. The hard parts usually aren't the login buttons. They're session persistence, deep linking, redirect handling, native SDK integration, and provider-specific edge cases.

This guide takes the production path for The Complete Guide to Supabase Auth in React Native (Email + OAuth + Apple Sign-. The core opinion is simple: on mobile, web-style OAuth is usually the wrong default. Native provider SDKs plus Supabase token exchange produce a better user experience and fewer moving parts when you ship to iOS and Android.

Table of Contents

• Why Production Auth is Harder Than Demos
  • The happy path is not the product
  • What production ready auth actually means
• Core Supabase Setup and Session Management
  • Start with the client config that mobile needs
  • Why AppState control matters
  • The minimum auth architecture I trust
• Implementing Email and Password Authentication
  • The straightforward part
  • The part that breaks in real apps
• Adding Social OAuth with a Native UX
  • Stop defaulting to browser OAuth on mobile
  • The native token exchange flow
  • When web OAuth is still acceptable
• Mastering Apple Sign-In for iOS Apps
  • Apple sign in is its own category
  • The implementation shape that holds up
  • What to save immediately
• Advanced Patterns and Troubleshooting
  • Identity linking can help or hurt
  • A practical debugging checklist

Why Production Auth is Harder Than Demos

Most auth demos optimize for the first five minutes. Production auth has to survive the next five months.

A frustrated developer looking down at a messy whiteboard diagram next to a laptop showing a login screen.

The happy path is not the product

A demo usually proves one thing: a user can authenticate once on one device in one environment. That isn't enough. Mobile auth breaks when the app backgrounds, when the OS kills it, when an email link opens outside the app, or when an OAuth callback returns to the wrong scheme.

Recent official guidance emphasizes that mobile auth in React Native depends on handling deep linking, redirect URLs, and session persistence correctly, and that the most common failure modes are OAuth callback handling and losing the session when the app is backgrounded or reopened, as noted in this referenced guidance.

Practical rule: If your auth flow only works while Metro is running and the app stays foregrounded, it isn't finished.

This is why developers get fooled by browser-shaped examples. A browser owns the full redirect loop and session model. A React Native app doesn't. Your app has to coordinate native lifecycle events, storage, URL handling, and platform-specific provider behavior.

What production ready auth actually means

In a React Native app, I consider auth production-ready when these conditions hold:

• Sessions persist correctly: users don't get kicked out after app restarts, app switching, or routine idle time.
• Refresh is automatic: token renewal happens without requiring a fresh sign-in every time the app becomes active.
• OAuth feels native: Google and Apple open their own system UI, not a clunky browser round trip unless you intentionally chose that trade-off.
• Verification returns to the app: email confirmation and password recovery can land back in the correct screen.
• Provider quirks are handled: Apple, in particular, has rules and behavior that you need to design around.

A lot of teams think auth is a UI task. It isn't. It's a runtime behavior problem. The login form is the easy part. The reliability work sits underneath it.

Here's the mistake I see most often: treating mobile auth like web auth with a thinner screen. That's how you end up bolting browser redirects onto an app that should have used native sign-in libraries from the start.

Core Supabase Setup and Session Management

If this layer is weak, every auth method above it becomes flaky. Email login, Google, Apple, magic links. They all depend on the same session backbone.

A four-step infographic illustrating the essential Supabase authentication workflow for mobile React Native applications.

Start with the client config that mobile needs

Supabase's React Native quickstart shows a client configured with autoRefreshToken: true, persistSession: true, and detectSessionInUrl: false, plus React Native storage on non-web platforms and an AppState listener to control refresh behavior in the foreground and background, in Supabase's React Native auth quickstart.

That setup matters because mobile auth isn't a one-time login event. It's continuous session management.

A solid baseline looks like this:

import { AppState, Platform } from 'react-native'
import AsyncStorage from '@react-native-async-storage/async-storage'
import 'react-native-url-polyfill/auto'
import { createClient, processLock } from '@supabase/supabase-js'

const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL!
const supabaseKey = process.env.EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY!

export const supabase = createClient(supabaseUrl, supabaseKey, {
  auth: {
    ...(Platform.OS !== 'web' ? { storage: AsyncStorage } : {}),
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
    lock: processLock,
  },
})

if (Platform.OS !== 'web') {
  AppState.addEventListener('change', (state) => {
    if (state === 'active') supabase.auth.startAutoRefresh()
    else supabase.auth.stopAutoRefresh()
  })
}

You can swap storage strategy depending on your app's security posture, but the pattern stays the same. Persist the session. Refresh it automatically. Don't rely on URL-session detection that was designed for the web.

For teams using prewired mobile templates, it helps to understand this foundation instead of treating it like magic. AppLighter's Supabase core concepts documentation is useful here because it frames the Supabase layer as an application backbone rather than just a database connection.

Why AppState control matters

Foreground and background behavior isn't cosmetic. It's part of auth correctness.

Without AppState-aware refresh handling, the app may look signed in while holding an aging session, or it may refresh at awkward times and create race conditions around startup. The point isn't to outsmart Supabase. The point is to cooperate with mobile lifecycle rules.

The app should restore trust quietly. Users shouldn't have to think about token refresh at all.

That one expectation drives a lot of architectural decisions. If users reopen the app and land directly in the right screen, the auth layer is doing its job. If they bounce through a loading state, then a forced sign-in, then a stale profile fetch, the auth layer is leaking implementation details into the product.

The minimum auth architecture I trust

I keep this part boring on purpose:

A few practical rules matter more than fancy abstractions:

• Initialize once: don't create fresh Supabase clients inside screens or hooks.
• Gate routes centrally: your navigator or root layout should decide whether the session exists.
• Treat startup as async: the app needs time to restore a persisted session before rendering protected screens.
• Separate auth state from profile data: a valid session and a fully loaded user profile are not the same thing.

If you're debugging random sign-outs, this layer is the first place to inspect. It usually isn't a provider bug. It's usually session wiring.

Implementing Email and Password Authentication

Email and password is still worth doing well. It's the fallback when social providers fail, the entry point for many internal apps, and the simplest auth path to reason about.

A person holding a smartphone displaying an email login screen with input fields and a button.

The straightforward part

The basic calls are simple:

async function signUp(email: string, password: string) {
  const { data, error } = await supabase.auth.signUp({ email, password })
  if (error) throw error
  return data
}

async function signIn(email: string, password: string) {
  const { data, error } = await supabase.auth.signInWithPassword({ email, password })
  if (error) throw error
  return data
}

The code isn't where people stumble. The mistake is assuming sign-up always creates a session immediately.

Supabase notes in its React Native guidance that on native mobile, email and password sign-in may require email verification before a session is created, so you need deep linking in place for the verification step. If you ignore that, users confirm their email and never get back into the app cleanly.

The part that breaks in real apps

Email verification is where mobile apps stop being simple. Once the user taps the confirmation link in their inbox, your app has to accept that incoming URL and route the user to the correct state.

That means you need all of the following aligned:

• A defined app scheme: your Expo app needs a stable scheme in app.json.
• Allowed redirect configuration: Supabase auth settings need the matching redirect target.
• URL handling in the app: the app must parse the incoming link and complete the auth state transition.
• A sensible screen target: don't dump users onto a blank root screen after verification.

A minimal Expo shape looks like this:

{
  "expo": {
    "scheme": "myapp"
  }
}

Then your auth flow should listen for incoming URLs at startup and while the app is running. The exact wiring depends on your navigation setup, but the product rule is stable: when the user verifies their email, they should return to a screen that explains what happened and moves them forward.

Don't treat email verification as a side quest. On mobile, it's part of the main auth flow.

A few design choices help a lot:

• Show explicit post-signup guidance: tell users they may need to verify before the session exists.
• Handle reopened apps gracefully: if the app launches from a verification link, process the link before rendering private routes.
• Avoid ambiguous success states: users shouldn't wonder whether the app already recognized their confirmation.

If you want email auth to feel finished, build the verification return path before polishing the sign-up form. That's the piece users remember when it fails.

Adding Social OAuth with a Native UX

This is the biggest architectural fork in the road. On mobile, you can imitate web OAuth, or you can use the native provider SDK and hand the resulting identity token to Supabase. I strongly recommend the second option for production apps.

A smartphone screen displaying social authentication options for Google, Facebook, and Apple in a React Native app.

Stop defaulting to browser OAuth on mobile

signInWithOAuth isn't wrong. It's just often the wrong fit for React Native. Browser-based OAuth introduces redirect complexity, deep-link handling, and a UX that feels less native than the provider's own sign-in sheet.

Supabase's practical production guidance for Expo and React Native is to use native sign-in libraries and then exchange the provider token with supabase.auth.signInWithIdToken(), which avoids browser-based OAuth flows and aligns with native provider UX, as described in Supabase's Expo and React Native social auth walkthrough.

That recommendation matches what tends to hold up in real apps. Native UX feels better. The control flow is clearer. Debugging is less painful because you're working with the provider SDK directly instead of juggling app state through a browser round trip.

If you're building with Expo or planning your overall mobile architecture, AppLighter's post on building an app with React Native is a useful companion because it pushes the same broader idea. Pick patterns that belong to native apps, not browser habits copied into a native shell.

The native token exchange flow

For Google, the flow should look like this:

1. The user taps your Google sign-in button.
2. The native Google SDK presents the provider UI.
3. The SDK returns an identity token.
4. Your app sends that token to Supabase with signInWithIdToken.
5. Supabase creates or restores the user session.

In code, the shape is straightforward:

import { GoogleSignin } from '@react-native-google-signin/google-signin'
import { supabase } from './supabase'

export async function signInWithGoogleNative() {
  await GoogleSignin.hasPlayServices()
  const result = await GoogleSignin.signIn()

  const idToken = result?.data?.idToken
  if (!idToken) throw new Error('Missing Google ID token')

  const { data, error } = await supabase.auth.signInWithIdToken({
    provider: 'google',
    token: idToken,
  })

  if (error) throw error
  return data
}

That model is cleaner because responsibilities are split properly. Google authenticates the Google identity. Supabase verifies the token and manages the app session. Your app coordinates the flow and UI.

Browser OAuth on mobile tends to create complexity in the least forgiving parts of the stack, redirects, resumed app state, and callback routing.

One implementation note matters a lot. Native SDKs require real native configuration. That means dev builds or production builds, not magical assumptions from Expo Go. If your social login plan depends on native libraries, build your development workflow around that early.

A short walkthrough can help you picture the UX differences before implementing it:

When web OAuth is still acceptable

There are cases where browser OAuth is still fine:

• Early prototypes: you need something working quickly and can tolerate redirect rough edges.
• Shared web and mobile logic: your team values one OAuth abstraction across platforms more than a perfect native flow.
• Providers without mature native support: sometimes you accept the trade-off because the SDK ecosystem is weak.

But those are trade-offs, not ideals. For Google and Apple in serious React Native apps, the native route is usually the one that ages better.

A simple comparison makes the decision clearer:

If you're choosing for an MVP that you expect to keep, I wouldn't optimize for the quickest demo. I'd optimize for the least painful production path.

Mastering Apple Sign-In for iOS Apps

Apple Sign-In isn't just another social button. It has its own platform expectations, setup steps, and data-handling quirks.

Apple sign in is its own category

Supabase supports Sign in with Apple in native apps, and its documentation distinguishes browser-based OAuth, native Apple Authentication Services, and browser JS usage. For native iOS apps, the practical path is native Apple auth, not a browser detour.

There is also an essential operational detail. Supabase's Apple auth docs require you to create an Apple Developer signing key and safely store the AuthKey_XXXXXXXXXX.p8 file. If that file is lost or exposed, it should be revoked and replaced immediately, as noted in Supabase's Apple auth documentation.

That requirement changes how you should think about Apple sign-in. This isn't a lightweight frontend feature. It's connected to Apple developer credentials and identity infrastructure.

The implementation shape that holds up

On Expo, the normal choice is expo-apple-authentication. The pattern mirrors the Google flow:

import * as AppleAuthentication from 'expo-apple-authentication'
import { supabase } from './supabase'

export async function signInWithApple() {
  const credential = await AppleAuthentication.signInAsync({
    requestedScopes: [
      AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
      AppleAuthentication.AppleAuthenticationScope.EMAIL,
    ],
  })

  const identityToken = credential.identityToken
  if (!identityToken) throw new Error('Missing Apple identity token')

  const { data, error } = await supabase.auth.signInWithIdToken({
    provider: 'apple',
    token: identityToken,
  })

  if (error) throw error
  return { data, credential }
}

A few things make Apple more fragile than people expect:

• Native-only assumptions: test in the actual environment you'll ship, not just a loose simulator flow.
• Credential management: keep the Apple key material secured and documented for your team.
• Redirect thinking: even when using native auth, your app still needs disciplined handling of auth state transitions.

The UX should feel minimal to the user. The implementation won't be.

What to save immediately

Apple has one production quirk that catches teams repeatedly. Apple only returns the user's name on the first sign-in. If you don't persist that information right away, you probably won't get another chance from later sign-ins.

That means your successful Apple sign-in path should do more than create a session. It should also update your user profile or metadata while you still have the name fields.

A safe mental model looks like this:

• collect the Apple credential
• send the token to Supabase
• create or restore the session
• immediately persist any first-login profile fields you received
• only then assume later sessions can rely on that data

Apple auth isn't done when the user gets in. It's done when you've saved the data Apple won't send twice.

Also be careful with app review expectations. If your app offers other third-party sign-in methods on iOS, Apple sign-in usually belongs in the same auth surface as a first-class option, not hidden in a secondary settings menu.

Advanced Patterns and Troubleshooting

Most auth bugs aren't caused by one huge mistake. They're caused by small mismatches across providers, app state, and user records.

Identity linking can help or hurt

Supabase Auth automatically links identities that share the same email address to a single user, but identity linking gets dangerous when email data is backfilled or set incorrectly. In the Supabase discussion on linking and provider flows, the practical advice is to decode and validate the JWT, extract the email, confirm the token was signed by the provider, and only then link or update the Supabase user record. The same discussion also notes that Apple only returns the user's name on the first sign-in, so those fields should be persisted immediately, in the Supabase identity linking discussion.

This matters when a user signs up with email first, then later uses Apple or Google with the same address. Auto-linking can be helpful. It can also produce confusing account behavior if your app writes profile data in the wrong order or triggers unwanted email confirmation states during migration work.

A few rules reduce risk:

• Trust provider identity before merging: don't merge records just because two client payloads look similar.
• Persist first-login provider data immediately: especially for Apple name fields.
• Keep auth identity separate from app profile logic: session creation and profile enrichment should be related, but not tangled.

For teams working through Supabase auth, storage, and policy design together, AppLighter's post on a React Native Supabase template with auth, RLS, and storage is helpful because it connects auth decisions to the rest of your backend model.

A practical debugging checklist

When auth feels random, I usually reduce it to a checklist instead of reading logs blindly.

• Session disappears after reopen: inspect client initialization, persistent storage wiring, and whether your app is restoring session state before rendering routes.
• OAuth works in test but not in builds: verify you're using the native provider library in a native-capable build environment, not assuming browser behavior.
• Email verification feels broken: trace the full deep-link return path from inbox tap to route handling.
• Apple user name is missing later: check whether you saved it during the very first successful sign-in.
• Multiple accounts appear unexpectedly: inspect email normalization and account linking logic before blaming Supabase.

I also recommend treating auth logs differently from general app logs. Log state transitions, not secrets. You want to know that sign-in started, provider returned, token exchange succeeded, session restored, and profile sync completed. You do not want tokens printed into debug output or error tracking.

Stable auth systems are boring in production because the team made the hard choices early.

If you're deciding where to spend effort, spend it on lifecycle handling, provider-native flows, and link routing. That's where React Native auth becomes reliable.

---

If you want a faster path to shipping this without wiring every moving part from scratch, AppLighter gives you an Expo-based starter kit with authentication and the surrounding app infrastructure already put together so you can focus on product work instead of rebuilding the same mobile foundation again.