---
title: Phone Authentication
description: >-
  Phone number authentication: iOS/Android reCAPTCHA and Play Integrity setup,
  Expo config, signInWithPhoneNumber(), verifyPhoneNumber() with
  PhoneAuthListener / PhoneAuthState / PhoneAuthSnapshot / PhoneAuthError, test
  phone numbers, linking a phone number, updatePhoneNumber(), re-authenticating
  with a phone credential, and the throwing linkWithPhoneNumber() /
  reauthenticateWithPhoneNumber() helpers.
next: /auth/email-link-auth
previous: /auth/social-auth
---
> ## Documentation Index
> Fetch the complete documentation index at: https://rnfirebase.io/llms.txt
> Use this file to discover all available pages before exploring further.

## Prerequisites

- `@react-native-firebase/app` and `@react-native-firebase/auth` installed and native config completed per [Authentication usage](/auth/usage) / [Getting Started](/). From v26, New Architecture is required for packages with a native bridge.
- **Phone** sign-in provider enabled on the [Firebase Console](https://console.firebase.google.com/project/_/authentication/providers).
- Platform app verification completed (reCAPTCHA / APNs / Play Integrity) per the sections below. Firebase Phone Auth is not available in every country; see Firebase [FAQs](https://firebase.google.com/support/faq/#develop).

Phone authentication lets users sign in with an SMS code. Phone numbers that end users provide for authentication are sent and stored by Google to improve spam and abuse prevention across Google services, including Firebase. Obtain appropriate end-user consent before using phone number sign-in.

Example Expo Router screen: https://github.com/invertase/react-native-firebase/blob/main/test-expo/app/auth/phone.tsx (connects to the Auth emulator).

# iOS Setup

Complete steps 1 and 2 from the [Firebase iOS phone auth docs](https://firebase.google.com/docs/auth/ios/phone-auth#enable-phone-number-sign-in-for-your-firebase-project). Re-download `GoogleService-Info.plist` when instructed, and add your custom URL scheme to the project plist so the reCAPTCHA flow can return to the app.

Phone auth requires app verification. Automatic verification uses data-only Firebase Cloud Messaging. Data-only FCM needs a physical device with background refresh enabled. On Simulator, or when background refresh is disabled, Auth falls back to reCAPTCHA. Use that path to confirm reCAPTCHA is configured.

For automated testing you can disable app verification via [`AuthSettings.appVerificationDisabledForTesting`](https://reference.rnfirebase.io/_react-native-firebase/auth/AuthSettings.html#appverificationdisabledfortesting) before any phone auth methods.

# Android Setup

Complete steps 1 and 2 from the [Firebase Android phone auth docs](https://firebase.google.com/docs/auth/android/phone-auth#enable-phone-number-sign-in-for-your-firebase-project).

To force reCAPTCHA instead of Play Integrity during manual testing, set [`appVerificationDisabledForTesting`](https://reference.rnfirebase.io/_react-native-firebase/auth/AuthSettings.html#appverificationdisabledfortesting) before [`verifyPhoneNumber`](https://reference.rnfirebase.io/_react-native-firebase/auth/verifyPhoneNumber.html).

# Expo Setup

Phone auth needs the `@react-native-firebase/auth` config plugin (in addition to `@react-native-firebase/app`). That plugin is required for phone auth; it is not required for every Auth provider. It [sets up reCAPTCHA](https://firebase.google.com/docs/auth/ios/phone-auth#set-up-recaptcha-verification) on iOS.

File: `app.json` (or `app.config.js`). Add the plugins, then create a [development build](https://docs.expo.dev/develop/development-builds/introduction/#use-libraries-with-native-code-that-arent) (Expo Go cannot host this native config). See [Expo install](/#installation-for-expo-projects).

```json
{
  "expo": {
    "plugins": ["@react-native-firebase/app", "@react-native-firebase/auth"]
  }
}
```

On Expo SDK 58+ (UIScene life cycle), the plugin patches `SceneDelegate` so Firebase Auth can handle reCAPTCHA redirect URLs with `Auth.auth().canHandle(_:)` before they reach Expo Router. That matches Firebase’s documented `scene(_:openURLContexts:)` path for an in-app reCAPTCHA return; Auth does not require a cold-start `willConnectTo` handler for this flow.

# Sign-in

`signInWithPhoneNumber` accepts a phone number, sends an SMS code, and returns a confirmation object. Call `confirm(code)` with the SMS code.

```jsx
import React, { useState, useEffect } from 'react';
import { Button, TextInput } from 'react-native';
import { getAuth, onAuthStateChanged, signInWithPhoneNumber } from '@react-native-firebase/auth';

function PhoneSignIn() {
  // If null, no SMS has been sent
  const [confirm, setConfirm] = useState(null);

  // verification code (OTP)
  const [code, setCode] = useState('');

  function handleAuthStateChanged(user) {
    if (user) {
      // Some Android devices auto-retrieve the SMS code and complete sign-in
      // without the user typing it. Hide the code UI and navigate away when
      // this fires; entering the same code again will fail because it was used.
    }
  }

  useEffect(() => {
    const subscriber = onAuthStateChanged(getAuth(), handleAuthStateChanged);
    return subscriber;
  }, []);

  async function handleSignInWithPhoneNumber(phoneNumber) {
    const confirmation = await signInWithPhoneNumber(getAuth(), phoneNumber);
    setConfirm(confirmation);
  }

  async function confirmCode() {
    try {
      await confirm.confirm(code);
    } catch {
      console.log('Invalid code.');
    }
  }

  if (!confirm) {
    return (
      <Button
        title="Phone Number Sign In"
        onPress={() => handleSignInWithPhoneNumber('+1 650-555-3434')}
      />
    );
  }

  return (
    <>
      <TextInput value={code} onChangeText={text => setCode(text)} />
      <Button title="Confirm Code" onPress={() => confirmCode()} />
    </>
  );
}
```

Upon successful sign-in, any [`onAuthStateChanged`](/auth/usage#listening-to-authentication-state) listeners receive the signed-in user.

# Native phone verification listener

`verifyPhoneNumber` is an RN Firebase-specific iOS/Android helper. It returns a `PhoneAuthListener` (promise-like, with `.on('state_changed', …)`). Snapshot payloads use `PhoneAuthSnapshot` (`state`, `verificationId`, `code`, `error`). State string values match `PhoneAuthState` (`CODE_SENT` / `AUTO_VERIFY_TIMEOUT` / `AUTO_VERIFIED` / `ERROR`). Error callbacks receive `PhoneAuthError`. Other platforms should use `signInWithPhoneNumber` / `PhoneAuthProvider` via the firebase-js-sdk bridge instead.

Awaiting the listener resolves at different points per platform. On iOS it resolves with the `CODE_SENT` snapshot. On Android it resolves when auto-retrieval completes (`AUTO_VERIFIED`) or times out (`AUTO_VERIFY_TIMEOUT`, 60 seconds by default), not when the SMS is sent. To show the code input as soon as the SMS leaves, listen for `PhoneAuthState.CODE_SENT` in `.on('state_changed', …)` instead of awaiting.

```js
import {
  PhoneAuthProvider,
  PhoneAuthState,
  getAuth,
  signInWithCredential,
  verifyPhoneNumber,
} from '@react-native-firebase/auth';

async function signInWithVerifyPhoneNumberListener(phoneNumber) {
  const listener = verifyPhoneNumber(getAuth(), phoneNumber);

  listener.on(
    'state_changed',
    snapshot => {
      switch (snapshot.state) {
        case PhoneAuthState.CODE_SENT:
          console.log('SMS sent', snapshot.verificationId);
          break;
        case PhoneAuthState.AUTO_VERIFIED:
          console.log('Instant verification', snapshot.code);
          break;
        case PhoneAuthState.AUTO_VERIFY_TIMEOUT:
          console.log('Auto-retrieval timed out');
          break;
        case PhoneAuthState.ERROR:
          console.log('Phone auth error state', snapshot.error);
          break;
        default:
          break;
      }
    },
    error => {
      console.log('PhoneAuthError', error.code, error.message, error.verificationId);
    },
  );

  const snapshot = await listener;
  if (!snapshot.verificationId) {
    throw new Error('No verificationId from verifyPhoneNumber');
  }

  // Prompt the user for the SMS code when auto-verification did not complete.
  const code = snapshot.code ?? '123456';
  const credential = PhoneAuthProvider.credential(snapshot.verificationId, code);
  return signInWithCredential(getAuth(), credential);
}

await signInWithVerifyPhoneNumberListener('+1 650-555-3434');
```

# Testing

For local test numbers, add your machine's SHA-1 debug key in the Firebase Console (see [Getting Started](/)).

In the [Firebase Console](https://console.firebase.google.com/project/_/authentication/providers), open the Phone provider → **Phone numbers for testing**. Add a number (for example `+44 7444 555666`) and a test code (for example `123456`). `signInWithPhoneNumber` with that number and code completes sign-in without sending SMS.

# MFA-like Account Creation

After creating a user with email/password, use `verifyPhoneNumber` and `linkWithCredential` to attach a phone number. That is an MFA-like account-creation flow only. Full MFA requires Identity Platform and the flows on [Multi-factor Auth](/auth/multi-factor-auth); see also [Identity Platform MFA](https://cloud.google.com/identity-platform/docs/web/mfa).

```jsx
import React, { useState, useEffect } from 'react';
import { Button, TextInput, Text } from 'react-native';
import {
  PhoneAuthProvider,
  getAuth,
  onAuthStateChanged,
  createUserWithEmailAndPassword,
  verifyPhoneNumber,
  linkWithCredential,
} from '@react-native-firebase/auth';

function PhoneVerification() {
  const [initializing, setInitializing] = useState(true);
  const [user, setUser] = useState(
    /** @type {import('@react-native-firebase/auth').User | null} */ (null),
  );
  // PhoneAuthSnapshot from verifyPhoneNumber (not a ConfirmationResult)
  const [snapshot, setSnapshot] = useState(null);
  const [code, setCode] = useState('');

  function handleAuthStateChanged(nextUser) {
    setUser(nextUser);
    if (initializing) {
      setInitializing(false);
    }
  }

  useEffect(() => {
    const subscriber = onAuthStateChanged(getAuth(), handleAuthStateChanged);
    return subscriber;
  }, []);

  async function createAccount() {
    try {
      await createUserWithEmailAndPassword(
        getAuth(),
        'jane.doe@example.com',
        'SuperSecretPassword!',
      );
      console.log('User account created & signed in!');
    } catch (error) {
      if (error.code === 'auth/email-already-in-use') {
        console.log('That email address is already in use!');
      }

      if (error.code === 'auth/invalid-email') {
        console.log('That email address is invalid!');
      }
      console.error(error);
    }
  }

  async function handlePhoneNumberVerification(phoneNumber) {
    setSnapshot(await verifyPhoneNumber(getAuth(), phoneNumber));
  }

  async function confirmCode() {
    try {
      const currentUser = getAuth().currentUser;
      if (!currentUser) {
        throw new Error('No user is signed in');
      }
      if (!snapshot?.verificationId) {
        throw new Error('No verificationId from verifyPhoneNumber');
      }
      const credential = PhoneAuthProvider.credential(snapshot.verificationId, code);
      const userCredential = await linkWithCredential(currentUser, credential);
      setUser(userCredential.user);
    } catch (error) {
      if (error.code === 'auth/invalid-verification-code') {
        console.log('Invalid code.');
      } else {
        console.log('Account linking error');
      }
    }
  }

  if (initializing) return null;

  if (!user) {
    return <Button title="Login" onPress={() => createAccount()} />;
  }

  if (!user.phoneNumber) {
    if (!snapshot) {
      return (
        <Button
          title="Verify Phone Number"
          onPress={() => handlePhoneNumberVerification('+1 650-555-3434')}
        />
      );
    }
    return (
      <>
        <TextInput value={code} onChangeText={text => setCode(text)} />
        <Button title="Confirm Code" onPress={() => confirmCode()} />
      </>
    );
  }

  return (
    <Text>
      Welcome! {user.phoneNumber} linked with {user.email}
    </Text>
  );
}
```

# Update or re-authenticate with a phone number

`updatePhoneNumber(user, credential)` replaces the phone number on the signed-in user with the number the credential was verified for. `reauthenticateWithCredential(user, credential)` accepts the same phone credential when a sensitive operation needs a recent sign-in. Both take a `PhoneAuthProvider.credential(verificationId, smsCode)` credential, and both reject when no user is signed in.

The flow is the same for both: start `verifyPhoneNumber` for the number, wait for `PhoneAuthState.CODE_SENT` to get the `verificationId`, then build the credential from the SMS code the user enters.

```js
import {
  PhoneAuthProvider,
  PhoneAuthState,
  getAuth,
  reauthenticateWithCredential,
  updatePhoneNumber,
  verifyPhoneNumber,
} from '@react-native-firebase/auth';

/** @returns {Promise<string>} */
function sendSmsCode(phoneNumber) {
  return new Promise((resolve, reject) => {
    verifyPhoneNumber(getAuth(), phoneNumber).on(
      'state_changed',
      snapshot => {
        if (snapshot.state === PhoneAuthState.CODE_SENT && snapshot.verificationId) {
          resolve(snapshot.verificationId);
        }
      },
      error => reject(error),
    );
  });
}

async function updateSignedInUserPhoneNumber(verificationId, smsCode) {
  const user = getAuth().currentUser;
  if (!user) {
    throw new Error('No user is signed in');
  }

  const credential = PhoneAuthProvider.credential(verificationId, smsCode);
  await updatePhoneNumber(user, credential);
}

async function reauthenticateWithSmsCode(verificationId, smsCode) {
  const user = getAuth().currentUser;
  if (!user) {
    throw new Error('No user is signed in');
  }

  const credential = PhoneAuthProvider.credential(verificationId, smsCode);
  return reauthenticateWithCredential(user, credential);
}

// Request a new SMS code for each operation.
const updateVerificationId = await sendSmsCode('+1 650-555-3434');
await updateSignedInUserPhoneNumber(updateVerificationId, '123456');

const reauthVerificationId = await sendSmsCode('+1 650-555-3434');
await reauthenticateWithSmsCode(reauthVerificationId, '654321');
```

The firebase-js-sdk helpers `linkWithPhoneNumber` and `reauthenticateWithPhoneNumber` throw on React Native Firebase. To attach a phone number to an existing user, follow [MFA-like Account Creation](#mfa-like-account-creation) and call `linkWithCredential`; to re-authenticate, use `reauthenticateWithCredential` as above.
