> For the complete documentation index, see [llms.txt](/llms.txt). # 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: ```swift 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. **Table** **Basic parameters:** | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | Your Web3Auth Client ID from the [Dashboard](https://developer.metamask.io/). It's a mandatory field of type `String`. | | `redirectUrl` | URL that Web3Auth will redirect API responses upon successful authentication. Use `{bundleId}://auth`. It's a mandatory field of type `String`. | | `web3AuthNetwork` | Web3Auth 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:** | 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. | | `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`. | **Struct** ```swift public struct Web3AuthOptions: Codable { public init( clientId: String, redirectUrl: String, originData: [String: String]? = nil, authBuildEnv: BuildEnv? = .production, sdkUrl: String? = nil, storageServerUrl: String? = nil, sessionSocketUrl: String? = nil, citadelServerUrl: String? = nil, authConnectionConfig: [AuthConnectionConfig]? = nil, whiteLabel: WhiteLabelData? = nil, dashboardUrl: String? = nil, accountAbstractionConfig: String? = nil, walletSdkUrl: String? = nil, includeUserDataInToken: Bool? = true, chains: [Chains]? = nil, defaultChainId: String? = "0x1", enableLogging: Bool? = false, sessionTime: Int? = nil, web3AuthNetwork: Web3AuthNetwork, useSFAKey: Bool? = nil, walletServicesConfig: WalletServicesConfig? = nil, mfaSettings: MfaSettings? = nil, sessionNamespace: String? = nil, wsEmbedDappClientId: String? = nil, useAAWithExternalWallet: Bool? = nil ) public init(clientId: String, web3AuthNetwork: Web3AuthNetwork, redirectUrl: String) } ``` ## 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](/embedded-wallets/dashboard/advanced/session-management/), whose default is 30 days, or 30 days if the dashboard returns none. ```swift 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](/embedded-wallets/sdk/ios/usage/getAccessToken/), [getIdentityToken](/embedded-wallets/sdk/ios/usage/getIdentityToken/), and [refreshSession](/embedded-wallets/sdk/ios/usage/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 | 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: `.eip155`, `.solana`, or `.other`. Default is `.eip155`. Wallet Services support EVM chains only. | | `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 ```swift 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 ```swift 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](/embedded-wallets/sdk/ios/advanced/wallet-services/) section. | Parameter | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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`. | ```swift 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](/embedded-wallets/sdk/ios/advanced/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](/embedded-wallets/sdk/ios/advanced/whitelabel/). ## 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