For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at the same URL with .md appended (or via Accept: text/markdown).
Skip to main content

Advanced configuration

The Web3Auth by MetaMask, Embedded Wallet 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 Embedded Wallets dashboard
        redirectUrl: "com.yourapp.bundleid://auth",
        web3AuthNetwork: .SAPPHIRE_MAINNET // or .SAPPHIRE_DEVNET
    )
)

Web3AuthOptions​

The constructor takes a Web3AuthOptions struct as input.

Web3AuthOptions provides two public initializers:

  • Web3AuthOptions(clientId:web3AuthNetwork:redirectUrl:) sets only the three required values.
  • The full initializer accepts every option listed below. Swift requires labeled arguments in declaration order, so pass clientId and redirectUrl first, and place web3AuthNetwork after sessionTime and before useSFAKey. See the Struct tab for the exact order.

Basic parameters:

ParameterDescription
clientIdYour Web3Auth Client ID from the Dashboard. It's a mandatory field of type String.
redirectUrlURL that Web3Auth will redirect API responses upon successful authentication. Use {bundleId}://auth. It's a mandatory field of type String.
web3AuthNetworkWeb3Auth Network: .SAPPHIRE_MAINNET, .SAPPHIRE_DEVNET, .MAINNET, .TESTNET, .CYAN, .AQUA, or .CELESTE. Mandatory field of type Web3AuthNetwork.
sessionTime?Session duration in seconds. Default is 30 days, the dashboard's session duration setting: when nil, the SDK uses the dashboard value, or 30 days (86400 * 30) if the dashboard returns none. Values above 30 days are clamped to 30 days. Accepts Int.
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. Default is "0x1" (Ethereum mainnet). Wallet Services open on the first chain in the chain list and use defaultChainId only when the list is empty.
enableLogging?Enable SDK logging. Default is false.

Advanced parameters:

ParameterDescription
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.
authBuildEnv?Build environment of the Web3Auth services: .production, .staging, or .testing. Default is .production. Takes BuildEnv (also available as the Web3AuthBuildEnv type alias) as a value.
originData?Signed allowlist entries, as [String: String]. The SDK merges these with the signed URLs from your dashboard allowlist.
includeUserDataInToken?Whether to include user data in the ID token. Default is true.
accountAbstractionConfig?Smart account configuration as a JSON String. If you don't set it, the SDK uses the smart account configuration from the dashboard.
useAAWithExternalWallet?Whether to use smart accounts with external wallets in Wallet Services. If you don't set it, the SDK derives it from the dashboard smart account wallet scope.
sessionNamespace?Custom namespace for session storage. Takes String as a value.
wsEmbedDappClientId?Client ID passed to Wallet Services. Takes String as a value.
sdkUrl?Override for the Web3Auth auth service URL. The default is the URL for authBuildEnv.
walletSdkUrl?Override for the Wallet Services URL. The default is the URL for authBuildEnv.
dashboardUrl?Override for the account dashboard URL used by manageMFA. The default is the URL for authBuildEnv.
storageServerUrl?Override for the session storage server URL. The default is the URL for authBuildEnv.
sessionSocketUrl?Override for the session socket server URL. The default is the URL for authBuildEnv.
citadelServerUrl?Override for the token-based session (Citadel) server URL. The default is the URL for authBuildEnv.

Session management​

Control how long users stay authenticated and how sessions persist. The SDK stores session data in the device's Keychain.

Key configuration options:

  • sessionTime - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again.
    • Maximum: 30 days (86400 * 30). Larger values are clamped to 30 days.
    • Default: 30 days. When you don't set sessionTime, the SDK uses the session duration configured in the dashboard, whose default is 30 days, or 30 days if the dashboard returns none.
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard
        redirectUrl: "com.yourapp.bundleid://auth",
        sessionTime: 86400 * 7, // 7 days (in seconds)
        web3AuthNetwork: .SAPPHIRE_MAINNET
    )
)

The SDK uses token-based sessions. After sign-in, you can call getAccessToken, getIdentityToken, and refreshSession to work with the session tokens.

note

Users who sign in with an idToken (single-factor authentication) don't get session tokens. For these users, getAccessToken and getIdentityToken throw Web3AuthError.noUserFound, and userInfo.idToken is nil.

Chains configuration​

The chains parameter lets you specify blockchain networks for Wallet Services (showWalletUI, request). If the dashboard returns a chains field, the SDK uses the dashboard chains for Wallet Services, even when that list is empty. The SDK uses chains from Web3AuthOptions only when the dashboard response has no chains field. Wallet Services open on the first chain in the list.

Chains fields​

FieldTypeRequiredDescription
chainIdStringYesChain ID in hex format (for example, "0x1" for Ethereum mainnet, "0x89" for Polygon).
rpcTargetStringYesRPC endpoint URL for the chain.
chainNamespaceChainNamespaceNoNamespace of the chain: .eip155, .solana, or .other. Default is .eip155. Wallet Services support EVM chains only.
decimals?Int?NoNumber of decimals for the native token. Default is 18.
blockExplorerUrl?String?NoURL of the block explorer for this chain.
displayName?String?NoHuman-readable name for the chain.
logo?String?NoURL of the chain's logo image.
ticker?String?NoTicker symbol for the native token (for example, "ETH").
tickerName?String?NoFull name of the native token (for example, "Ethereum").

Interface​

public struct Chains: Codable {
    public init(
        chainNamespace: ChainNamespace = ChainNamespace.eip155,
        decimals: Int? = 18,
        blockExplorerUrl: String? = nil,
        chainId: String,
        displayName: String? = nil,
        logo: String? = nil,
        rpcTarget: String,
        ticker: String? = nil,
        tickerName: String? = nil
    )
}

public enum ChainNamespace: String, Codable {
    case eip155
    case solana
    case other
}

Example​

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

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

ParameterDescription
confirmationStrategy?Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy. Default is .defaultStrategy. The dashboard's confirmation modal setting overrides this value when set.
whiteLabel?Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts WhiteLabelData.
enableKeyExport?Whether users can export their private key from the Wallet Services UI. Accepts Bool.
web3Auth = try await Web3Auth(
    options: Web3AuthOptions(
        clientId: "YOUR_WEB3AUTH_CLIENT_ID",
        redirectUrl: "com.yourapp.bundleid://auth",
        web3AuthNetwork: .SAPPHIRE_MAINNET,
        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
On this page