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

# Multi-factor authentication in iOS SDK

Multi-Factor Authentication (MFA) adds 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. Choose from device, social, backup factor (seed phrase), and password factors to secure 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 recover your account if you lose access to your original device or need to sign in on 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 MFA level[​](#enable-using-the-mfa-level "Direct link to Enable using the MFA level")

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. Four MFA level values are available.

Note

If you're using default auth connections, your users may have set up MFA on other dapps that also use default Embedded Wallets auth connections. In this case, the MFA screen continues to appear if the user has enabled MFA on other dapps. MFA can't be turned off once enabled.

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

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

### Usage[​](#usage "Direct link to Usage")

```
import Web3Auth

let web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth"
    )
)

let result = try await web3Auth.connectTo(
    loginParams: LoginParams(
        authConnection: .GOOGLE,
        mfaLevel: .MANDATORY
    )
)

```

## Explicitly enable MFA[​](#explicitly-enable-mfa "Direct link to Explicitly enable MFA")

The `enableMFA` method triggers the MFA setup flow for users. It takes `LoginParams`, which is used during custom auth connections. If you're using default sign-in providers, you don't need to pass `LoginParams`. For custom JWT auth connections, pass the valid JWT token in `LoginParams`.

- Default Auth Connection
- Custom JWT Auth Connection

```
do {
  let isMFAEnabled = try await web3Auth.enableMFA()
} catch {
  print(error.localizedDescription)
  // Handle Error
}

```

```
do {
    let loginParams = LoginParams(
        authConnection: .CUSTOM,
        authConnectionId: "your-auth-connection-id",
        idToken: "your_jwt_token"
    )

    let isMFAEnabled = try await web3Auth.enableMFA(loginParams)
} catch {
    print(error.localizedDescription)
    // Handle Error
}

```

## Configure Multi-Factor Authentication settings[​](#configure-multi-factor-authentication-settings "Direct link to Configure Multi-Factor Authentication settings")

Configure the order of MFA or enable/disable MFA types by passing the `mfaSettings` object in `Web3AuthOptions`.

Note

- At least two factors are mandatory when setting up `mfaSettings`.
- If you set `mandatory: true` for all factors, the user must set up all factors.
- If you set `mandatory: false` for all factors, the user can skip MFA setup, but at least two factors are still 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 ones, but must set up at least two factors total.
- The `priority` field sets the order of the factors. The lowest priority value is set up first; the highest is set up last.

### `MfaSettings` parameters[​](#mfasettings-parameters "Direct link to mfasettings-parameters")

`MfaSettings` configures which MFA factor types are available.

- Table
- Class

| 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. |

```
public struct MfaSettings: Codable {
    public init(deviceShareFactor: MfaSetting?, backUpShareFactor: MfaSetting?, socialBackupFactor: MfaSetting?, passwordFactor: MfaSetting?, passkeysFactor: MfaSetting?, authenticatorFactor: MfaSetting?) {
        self.deviceShareFactor = deviceShareFactor
        self.backUpShareFactor = backUpShareFactor
        self.socialBackupFactor = socialBackupFactor
        self.passwordFactor = passwordFactor
        self.passkeysFactor = passkeysFactor
        self.authenticatorFactor = authenticatorFactor
    }

    let deviceShareFactor: MfaSetting?
    let backUpShareFactor: MfaSetting?
    let socialBackupFactor: MfaSetting?
    let passwordFactor: MfaSetting?
    let passkeysFactor: MfaSetting?
    let authenticatorFactor: MfaSetting?
}

```

### `MfaSetting` parameters[​](#mfasetting-parameters "Direct link to mfasetting-parameters")

`MfaSetting` configures the behavior of an individual MFA factor.

- Table
- Class

| 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 accepts Bool as a value.                           |

```
public struct MfaSetting: Codable {
    public init(enable: Bool, priority: Int?, mandatory: Bool? = nil) {
        self.enable = enable
        self.priority = priority
        self.mandatory = mandatory
    }

    let enable: Bool
    let priority: Int?
    let mandatory: Bool?
}

```

### Usage[​](#usage-1 "Direct link to Usage")

```
import Web3Auth

let web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth",
        mfaSettings: MfaSettings(
            deviceShareFactor: MfaSetting(enable: true, priority: 1),
            backUpShareFactor: MfaSetting(enable: true, priority: 2),
            socialBackupFactor: MfaSetting(enable: true, priority: 3),
            passwordFactor: MfaSetting(enable: true, priority: 4),
            passkeysFactor: MfaSetting(enable: true, priority: 5),
            authenticatorFactor: MfaSetting(enable: true, priority: 6)
        )
    )
)

let result = try await web3Auth.connectTo(
    loginParams: LoginParams(
        authConnection: .GOOGLE,
        mfaLevel: .MANDATORY
    )
)

```