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

# Advanced configuration

The Embedded Wallets SDK offers configuration options to customize authentication flows, UI appearance, blockchain integrations, and security features for your dapp.

## Configuration structure[​](#configuration-structure "Direct link to Configuration structure")

Pass options to the `Web3Auth` constructor during setup:

```
import Web3Auth

web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard
        web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
        redirectUrl: "com.yourapp.bundleid://auth"
    )
)

```

### `Web3AuthOptions`[​](#web3authoptions "Direct link to web3authoptions")

The constructor takes a `Web3AuthOptions` struct as input.

- Table
- Struct

**Basic parameters:**

| Parameter       | Description                                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| clientId        | Your Web3Auth Client ID from the [Dashboard](https://developer.metamask.io/). It's a mandatory field of type String.                 |
| web3AuthNetwork | Web3Auth Network: .SAPPHIRE_MAINNET, .SAPPHIRE_DEVNET, .MAINNET, .CYAN, .AQUA, or .TESTNET. Mandatory field of type Web3AuthNetwork. |
| redirectUrl     | URL that Web3Auth will redirect API responses upon successful authentication. It's a mandatory field of type String.                 |
| sessionTime?    | Session duration in seconds. Default is 86400 * 30 (30 days). Maximum is 30 days.                                                    |
| useSFAKey?      | Use SFA key to get single factor auth key. Default is false. Useful for wallet pre-generation and SFA mode.                          |
| defaultChainId? | Default chain ID to use. Default is "0x1" (Ethereum mainnet).                                                                        |
| enableLogging?  | Enable SDK logging. Default is false.                                                                                                |

**Advanced parameters:**

| Parameter             | Description                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| whiteLabel?           | Whitelabel options for custom UI, branding, and translations. Takes WhiteLabelData as a value.                                          |
| authConnectionConfig? | Auth connection config for custom auth connections. Takes [AuthConnectionConfig] as a value.                                            |
| mfaSettings?          | Configure MFA settings for authentication. Takes MfaSettings as a value.                                                                |
| chains?               | Custom chain configuration for blockchain networks. Takes [Chains] as a value. See [Chains configuration](#chains-configuration) below. |
| walletServicesConfig? | Configuration for Wallet Services including whitelabel options. Takes WalletServicesConfig as a value.                                  |

```
public struct Web3AuthOptions: Codable {
    let clientId: String
    var redirectUrl: String
    let authBuildEnv: BuildEnv?
    var authConnectionConfig: [AuthConnectionConfig]?
    var whiteLabel: WhiteLabelData?
    var chains: [Chains]?
    var defaultChainId: String?
    let enableLogging: Bool?
    let sessionTime: Int
    var web3AuthNetwork: Web3AuthNetwork
    var useSFAKey: Bool?
    var walletServicesConfig: WalletServicesConfig?
    var mfaSettings: MfaSettings?
}

```

## Session management[​](#session-management "Direct link to Session management")

Control how long users stay authenticated and how sessions persist. The session key is stored in the device's encrypted Keychain.

**Key configuration options:**

- `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again.  
  - Minimum: 1 second (`1`).
  - Maximum: 30 days (`86400 * 30`).
  - Default: 30 days (`86400 * 30`).

```
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth",
        sessionTime: 86400 * 7 // 7 days (in seconds)
    )
)

```

## Chains configuration[​](#chains-configuration "Direct link to Chains configuration")

The `chains` parameter lets you specify custom blockchain networks for the SDK. When set, these chains are used by Wallet Services (`showWalletUI`, `request`) in addition to any chains configured in the project dashboard.

### `Chains` fields[​](#chains-fields "Direct link to chains-fields")

| Field             | Type           | Required | Description                                                                           |
| ----------------- | -------------- | -------- | ------------------------------------------------------------------------------------- |
| chainId           | String         | Yes      | Chain ID in hex format (for example, "0x1" for Ethereum mainnet, "0x89" for Polygon). |
| rpcTarget         | String         | Yes      | RPC endpoint URL for the chain.                                                       |
| chainNamespace    | ChainNamespace | No       | Namespace of the chain. Accepts .eip155, .solana, or .other. Default is .eip155.      |
| decimals?         | Int?           | No       | Number of decimals for the native token. Default is 18.                               |
| blockExplorerUrl? | String?        | No       | URL of the block explorer for this chain.                                             |
| displayName?      | String?        | No       | Human-readable name for the chain.                                                    |
| logo?             | String?        | No       | URL of the chain's logo image.                                                        |
| ticker?           | String?        | No       | Ticker symbol for the native token (for example, "ETH").                              |
| tickerName?       | String?        | No       | Full name of the native token (for example, "Ethereum").                              |

### Interface[​](#interface "Direct link to Interface")

```
public struct Chains: Codable {
    public let chainNamespace: ChainNamespace
    public let decimals: Int?
    public let blockExplorerUrl: String?
    public let chainId: String?
    public let displayName: String?
    public let logo: String?
    public let rpcTarget: String
    public let ticker: String?
    public let tickerName: String?
}

```

### Example[​](#example "Direct link to Example")

```
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth",
        chains: [
            Chains(
                chainId: "0x89",
                rpcTarget: "https://rpc.ankr.com/polygon",
                displayName: "Polygon Mainnet",
                ticker: "MATIC",
                tickerName: "Matic",
                blockExplorerUrl: "https://polygonscan.com"
            )
        ]
    )
)

```

## Wallet Services configuration[​](#wallet-services-configuration "Direct link to Wallet Services configuration")

The `walletServicesConfig` parameter in `Web3AuthOptions` customizes the behavior of the wallet UI (`showWalletUI`) and request signing (`request`). For full configuration options, see the [Wallet Services](/embedded-wallets/sdk/ios/advanced/wallet-services/) section.

| Parameter             | Description                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| confirmationStrategy? | Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy. Default is .defaultStrategy.                           |
| whiteLabel?           | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts WhiteLabelData. |

```
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth",
        walletServicesConfig: WalletServicesConfig(
            confirmationStrategy: .modal
        )
    )
)

```

## Custom authentication methods[​](#custom-authentication-methods "Direct link to Custom authentication methods")

Control the sign-in options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](/embedded-wallets/sdk/ios/advanced/custom-authentication/) section.

## UI customization[​](#ui-customization "Direct link to UI customization")

Customize the Embedded Wallets sign-in screens to match your dapp's design. For complete customization options, see [Whitelabeling and UI customization](/embedded-wallets/sdk/ios/advanced/whitelabel/).

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

Add security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see [Multi-Factor Authentication](/embedded-wallets/sdk/ios/advanced/mfa/).

**Key configuration options:**

- `mfaSettings` - Configure MFA settings for different authentication flows
- `mfaLevel` - Control when users are prompted to set up MFA