> For the complete documentation index, see [llms.txt](/llms.txt).

# Multi-factor authentication in React Native SDK

The Multi-Factor Authentication feature lets users create a backup share (recovery phrase), which they use to log in from a new device or recover their account if they lose their device.

note

This is a paid feature and the minimum [pricing plan](https://web3auth.io/pricing.html) to use this SDK in a production environment is the **Scale Plan**. You can use this feature in Web3Auth Sapphire Devnet network for free.

## Default MFA level[​](#default-mfa-level "Direct link to Default MFA level")

Set `mfaLevel` in `web3AuthOptions` to control when the MFA setup prompt is shown globally:

web3authConfig.ts

```
import { WEB3AUTH_NETWORK, MFA_LEVELS, type Web3AuthContextConfig } from '@web3auth/react-native-sdk'

const web3AuthConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    clientId: 'YOUR_CLIENT_ID',
    redirectUrl: 'yourapp://auth',
    network: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
    chains: [...],
    mfaLevel: MFA_LEVELS.DEFAULT,
  },
}

```

| MFA_LEVELS value     | Behavior                                                       |
| -------------------- | -------------------------------------------------------------- |
| MFA_LEVELS.DEFAULT   | Shows the MFA screen on every third login.                     |
| MFA_LEVELS.OPTIONAL  | Shows the MFA screen on every login, but the user can skip it. |
| MFA_LEVELS.MANDATORY | MFA setup is required immediately after the first login.       |
| MFA_LEVELS.NONE      | MFA setup screen is never shown.                               |

You can also override `mfaLevel` on a per-login basis by passing it to `connectTo`:

```
import { Button } from 'react-native'
import { AUTH_CONNECTION, MFA_LEVELS, useWeb3AuthConnect } from '@web3auth/react-native-sdk'

function MfaLoginView() {
  const { connectTo, loading } = useWeb3AuthConnect()

  const handleLogin = async () => {
    await connectTo({
      authConnection: AUTH_CONNECTION.GOOGLE,
      mfaLevel: MFA_LEVELS.MANDATORY,
    })
  }

  return <Button title="Sign in" disabled={loading} onPress={handleLogin} />
}

```

caution

If a user has already enabled MFA through another app that uses the same Web3Auth verifier, the MFA screen will continue to appear regardless of the `mfaLevel` setting. MFA cannot be disabled once it has been enabled by the user.

## Runtime MFA management[​](#runtime-mfa-management "Direct link to Runtime MFA management")

Use the `useEnableMFA` and `useManageMFA` hooks to let users set up or update their MFA factors from within your app:

```
import { useEnableMFA, useManageMFA } from '@web3auth/react-native-sdk'

function MFAControls() {
  const { enableMFA, loading: enabling } = useEnableMFA()
  const { manageMFA, loading: managing } = useManageMFA()

  return (
    <View>
      <Button title="Enable MFA" disabled={enabling} onPress={() => enableMFA()} />
      <Button title="Manage MFA" disabled={managing} onPress={() => manageMFA()} />
    </View>
  )
}

```

## MFA factor order (Scale plan and above)[​](#mfa-factor-order-scale-plan-and-above "Direct link to MFA factor order (Scale plan and above)")

note

Configuring `mfaSettings` is a paid feature. See [pricing](https://web3auth.io/pricing.html). You can test it on `sapphire_devnet` at no cost.

Pass a `mfaSettings` object to configure which MFA factors are available and in what order they are shown:

```
import { type MfaSettings } from '@web3auth/react-native-sdk'

const mfaSettings: MfaSettings = {
  deviceShareFactor: { enable: true, priority: 1, mandatory: true },
  backUpShareFactor: { enable: true, priority: 2, mandatory: true },
  socialBackupFactor: { enable: true, priority: 3, mandatory: false },
  passwordFactor: { enable: true, priority: 4, mandatory: false },
  passkeysFactor: { enable: true, priority: 5, mandatory: false },
  authenticatorFactor: { enable: true, priority: 6, mandatory: false },
}

const web3AuthConfig: Web3AuthContextConfig = {
  web3AuthOptions: {
    ...
    mfaLevel: MFA_LEVELS.MANDATORY,
    mfaSettings,
  },
}

```

### `mfaSettings` rules[​](#mfasettings-rules "Direct link to mfasettings-rules")

- At least two factors must be marked `mandatory: true`.
- The `priority` field determines the display order (lower = shown first).
- If all factors have `mandatory: false`, the user can still skip the screen. At least two must be set up overall.

### Available MFA factors[​](#available-mfa-factors "Direct link to Available MFA factors")

| Factor key          | Description                         |
| ------------------- | ----------------------------------- |
| deviceShareFactor   | Device-bound share (default factor) |
| backUpShareFactor   | Downloadable recovery phrase        |
| socialBackupFactor  | OAuth-based recovery                |
| passwordFactor      | Password-protected recovery share   |
| passkeysFactor      | Passkey-based recovery              |
| authenticatorFactor | TOTP authenticator app              |

### Related[​](#related "Direct link to Related")

- [useEnableMFA hook reference](/embedded-wallets/sdk/react-native/hooks/useEnableMFA/)
- [useManageMFA hook reference](/embedded-wallets/sdk/react-native/hooks/useManageMFA/)