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

# Multi-factor authentication

At Web3Auth, we prioritize your security by offering Multi-Factor Authentication (MFA). MFA is an extra layer of protection that verifies your identity when accessing your account. To ensure ownership, you must provide two or more different backup factors. You have the option to choose from the device, social, backup factor (seed phrase), and password factors to guarantee access to your web3 account. Once you create a recovery factor, MFA is enabled, and your keys are divided into three shares for offchain multi-sig, making the key self-custodial. With backup factors, you can easily recover your account if you lose access to your original device or helps login into a new 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.

## Enable using the Multi-Factor Authentication level

For a dapp, we provide various options to set up MFA. You can customize the MFA screen by passing the `mfaLevel` parameter in the `connectTo` method. You can enable or disable a backup factor and change their order. Currently, there are four values for MFA level.

Note

If you are using default auth connections, your users may have set up MFA on other dapps that also use default Embedded Wallets connections. In this case, the MFA screen will continue to appear if the user has enabled MFA on other dapps. This is because MFA cannot be turned off once it is enabled.

### Multi-Factor Authentication level options

| MFA Level | Description                                                |
| --------- | ---------------------------------------------------------- |
| DEFAULT   | Shows the MFA screen every third login.                    |
| OPTIONAL  | Shows the MFA screen on every login, but user can skip it. |
| MANDATORY | Makes it mandatory to set up MFA after first login.        |
| NONE      | Skips the MFA setup screen.                                |

### Usage

```dart
Web3AuthFlutter.connectTo(
  LoginParams(
    authConnection: AuthConnection.google,
    mfaLevel: MFALevel.MANDATORY,
  ),
);

```

## Explicitly enable Multi-Factor Authentication

The `enableMFA` method is used to trigger MFA setup flow for users. The method takes optional `LoginParams` for custom connections. If you are using default social login providers, you don't need to pass `LoginParams`. If you are using custom JWT connections, pass the JWT token in `loginParams` using `LoginParams.idToken`.

**Default connection**

Usage

```dart
try {
  await Web3AuthFlutter.enableMFA();
} on UserCancelledException {
  log("User cancelled.");
} catch(e) {
  log("Unknown exception occurred");
}

```

**Custom JWT connection**

Usage

```dart
try {
    final loginParams = LoginParams(
      authConnection: AuthConnection.custom,
      authConnectionId: "YOUR_AUTH_CONNECTION_ID",
      idToken: "YOUR_JWT_TOKEN",
    );

    await Web3AuthFlutter.enableMFA(loginParams: loginParams);

} on UserCancelledException { log("User cancelled."); } catch(e) { log("Unknown exception occurred"); }


```

## Configure Multi-Factor Authentication settings

You can configure the order of MFA, and enable or disable MFA type by passing the `mfaSettings` parameter in `Web3AuthOptions` during initialization.

Note

- At least two factors are mandatory when setting up the mfaSettings.
- If you set `mandatory: true` for all factors, the user must set up all four factors.
- If you set `mandatory: false` for all factors, the user can skip setting up MFA. But at least two factors are mandatory.
- If you set `mandatory: true` for some factors and `mandatory: false` for others, the user must set up the mandatory factors and can skip the optional factors. But, the user must set up at least two factors.
- The `priority` field is used to set the order of the factors. The factor with the lowest priority will be the first factor to be set up. The factor with the highest priority will be the last factor to be set up.

### Parameters - `MfaSettings`

`MfaSettings` allows you to set the type of the MFA.

**Table**

| Parameter              | Description                                                              |
| ---------------------- | ------------------------------------------------------------------------ |
| `deviceShareFactor?`   | MFA setting for deviceShareFactor. It accepts `MfaSetting` as a value.   |
| `backUpShareFactor?`   | MFA setting for backUpShareFactor. It accepts `MfaSetting` as a value.   |
| `socialBackupFactor?`  | MFA setting for socialBackupFactor. It accepts `MfaSetting` as a value.  |
| `passwordFactor?`      | MFA setting for passwordFactor. It accepts `MfaSetting` as a value.      |
| `passkeysFactor?`      | MFA setting for passkeysFactor. It accepts `MfaSetting` as a value.      |
| `authenticatorFactor?` | MFA setting for authenticatorFactor. It accepts `MfaSetting` as a value. |

**Class**

```dart
class MfaSettings {
  final MfaSetting? deviceShareFactor;
  final MfaSetting? backUpShareFactor;
  final MfaSetting? socialBackupFactor;
  final MfaSetting? passwordFactor;
  final MfaSetting? passkeysFactor;
  final MfaSetting? authenticatorFactor;

  MfaSettings({
    this.deviceShareFactor,
    this.backUpShareFactor,
    this.socialBackupFactor,
    this.passwordFactor,
    this.passkeysFactor,
    this.authenticatorFactor,
  });

  Map<String, dynamic> toJson() {
    return {
      'deviceShareFactor': deviceShareFactor,
      'backUpShareFactor': backUpShareFactor,
      'socialBackupFactor': socialBackupFactor,
      'passwordFactor': passwordFactor,
      'passkeysFactor': passkeysFactor,
      'authenticatorFactor': authenticatorFactor,
    };
  }
}

```

### Parameters - `MfaSetting`

`MfaSetting` allows you to configure the behavior of an individual MFA factor.

**Table**

| Parameter    | Description                                                                     |
| ------------ | ------------------------------------------------------------------------------- |
| `enable`     | Enable/Disable MFA. It accepts `bool` as a value.                               |
| `priority?`  | Priority of MFA. It accepts `int` as a value, where valid range is from 1 to 4. |
| `mandatory?` | Mandatory/Optional MFA. It acccepts `bool` as a value.                          |

**Class**

```dart
class MfaSetting {
  final bool enable;
  final int? priority;
  final bool? mandatory;

  MfaSetting({required this.enable, this.priority, this.mandatory});

  Map<String, dynamic> toJson() {
    return {'enable': enable, 'priority': priority, 'mandatory': mandatory};
  }
}

```

### Usage

```dart
Future<void> initWeb3Auth() async {

  late final String redirectUrl;
  if (Platform.isAndroid) {
    redirectUrl = 'w3a://com.example.w3aflutter';
  } else {
    redirectUrl = 'com.example.w3aflutter://auth';
  }


  await Web3AuthFlutter.init(
    Web3AuthOptions(
    clientId: "WEB3AUTH_CLIENT_ID",
    web3AuthNetwork: Web3AuthNetwork.sapphire_mainnet,
    redirectUrl: redirectUrl,
    mfaSettings: MfaSettings(
      deviceShareFactor: MfaSetting(
        enable: true,
        priority: 4,
        mandatory: true,
      ),
      backUpShareFactor: MfaSetting(
        enable: true,
        priority: 2,
        mandatory: true,
      ),
      socialBackupFactor: MfaSetting(
        enable: true,
        priority: 3,
        mandatory: false,
      ),
      passwordFactor: MfaSetting(
        enable: true,
        priority: 1,
        mandatory: true,
      ),
      passkeysFactor: MfaSetting(
        enable: true,
        priority: 5,
        mandatory: true,
      ),
      authenticatorFactor: MfaSetting(
        enable: true,
        priority: 6,
        mandatory: true,
      ),
    ),
  );

  await Web3AuthFlutter.initialize();
}

```