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

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 Web3Auth Dashboard
        web3AuthNetwork: .SAPPHIRE_MAINNET, // or .SAPPHIRE_DEVNET
        redirectUrl: "com.yourapp.bundleid://auth"
    )
)

Web3AuthOptions

The constructor takes a Web3AuthOptions struct as input.

• Table
• Struct

Basic parameters:

Parameter	Description
clientId	Your Web3Auth Client ID from the Dashboard. 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 pregeneration 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 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

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 Web3Auth Dashboard
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        redirectUrl: "com.yourapp.bundleid://auth",
        sessionTime: 86400 * 7 // 7 days (in seconds)
    )
)

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

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

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

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

The walletServicesConfig parameter in Web3AuthOptions customizes the behavior of the wallet UI (showWalletUI) and request signing (request). For full configuration options, see the Smart Accounts 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

Control the sign-in options presented to your users. For detailed configuration options and implementation examples, see the custom authentication section.

UI customization

Customize the Embedded Wallets sign-in screens to match your dapp's design. For complete customization options, see Whitelabeling and UI customization.

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.

Key configuration options:

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