> For the complete documentation index, see [llms.txt](/llms.txt). # Advanced configuration The Embedded Wallets SDK provides extensive configuration options that allow you to customize authentication flows, UI appearance, blockchain integrations, and security features to meet your application's specific requirements. ## Configuration structure When setting up Embedded Wallets, you'll pass in the options to the constructor. This consists of: ```dart import 'package:web3auth_flutter/web3auth_flutter.dart'; import 'package:web3auth_flutter/enums.dart'; import 'package:web3auth_flutter/input.dart'; import 'package:web3auth_flutter/output.dart'; import 'dart:io'; Future initWeb3Auth() async { late final String redirectUrl; if (Platform.isAndroid) { redirectUrl = 'w3a://com.example.w3aflutter'; } else { redirectUrl = 'com.example.w3aflutter://auth'; } await Web3AuthFlutter.init(Web3AuthOptions( clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard dashboard web3AuthNetwork: Web3AuthNetwork.sapphire_mainnet, // or Web3AuthNetwork.sapphire_devnet redirectUrl: redirectUrl, )); } ``` ### `Web3AuthOptions` The Web3Auth Constructor takes an object with `Web3AuthOptions` as input. **Table** | Parameter | Description | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | Your Web3Auth Client ID from the [dashboard](https://developer.metamask.io/). Mandatory `String`. | | `web3AuthNetwork` | Web3Auth Network: `sapphire_mainnet`, `sapphire_devnet`, `mainnet`, `cyan`, `aqua`, or `testnet`. Mandatory `Web3AuthNetwork`. | | `redirectUrl` | URL that Web3Auth redirects to after successful authentication. Mandatory `String`. | | `authBuildEnv?` | Web3Auth build environment, used for internal testing. Takes `BuildEnv.production`, `BuildEnv.staging`, or `BuildEnv.testing`. Default is `BuildEnv.production`. | | `whiteLabel?` | Whitelabel options for custom UI, branding, and translations. Takes `WhiteLabelData` as a value. | | `authConnectionConfig?` | Auth connection config for custom connections. Takes `List` as a value. | | `chains?` | Chain configuration for Wallet Services and signing. Takes `List` as a value. On Android, only the first entry in the list is passed to the native SDK. | | `defaultChainId?` | Default chain ID from the `chains` list. | | `mfaSettings?` | Configure MFA settings for authentication. Takes `MfaSettings` as a value. | | `sessionTime?` | Session duration in seconds. Default is 30 days, which is also the maximum. When unset, the SDK uses the session time set in your dashboard project, if any. | | `walletServicesConfig?` | Wallet Services configuration, such as the confirmation strategy and key export. Takes `WalletServicesConfig` as a value. | | `useSFAKey?` | Use SFA key to get single factor auth key. Default is `false`. Useful for wallet pre-generation and SFA mode. | | `includeUserDataInToken?` | Whether to include user data in the identity token. Default is `true`. | | `enableLogging?` | Enables native SDK logs. Default is `false`. | | `originData?` | Map of allowlisted origins to their signatures. Takes `Map` as a value. | | `sessionNamespace?` | Custom namespace for the session. | | `accountAbstractionConfig?` | Account abstraction configuration as a JSON `String`. | | `wsEmbedDappClientId?` | Optional dapp client ID for the Wallet Services embed. | | `useAAWithExternalWallet?` | Use account abstraction with external wallets. When unset, the value comes from your project configuration. | | `citadelServerUrl?` | Custom auth session (citadel) service URL. When unset, the SDK uses the default URL for `authBuildEnv`. | | `sdkUrl?` | Custom Auth service URL. When unset, the SDK uses the default URL for `authBuildEnv`. | | `walletSdkUrl?` | Custom Wallet Services URL. When unset, the SDK uses the default URL for `authBuildEnv`. | | `dashboardUrl?` | Custom account dashboard URL. When unset, the SDK uses the default URL for `authBuildEnv`. | | `storageServerUrl?` | Custom session storage service URL. When unset, the SDK uses the default URL for `authBuildEnv`. | | `sessionSocketUrl?` | Custom session socket URL. When unset, the SDK uses the default URL for `authBuildEnv`. | **Class** ```dart class Web3AuthOptions { final String clientId; final String redirectUrl; final Map? originData; final BuildEnv? authBuildEnv; final String? sdkUrl; String? storageServerUrl; String? sessionSocketUrl; String? citadelServerUrl; List? authConnectionConfig; final WhiteLabelData? whiteLabel; final String? dashboardUrl; String? accountAbstractionConfig; final String? walletSdkUrl; String? sessionNamespace; bool? includeUserDataInToken; List? chains; String? defaultChainId; bool enableLogging; final int? sessionTime; final Web3AuthNetwork web3AuthNetwork; final bool? useSFAKey; final WalletServicesConfig? walletServicesConfig; final MfaSettings? mfaSettings; final String? wsEmbedDappClientId; final bool? useAAWithExternalWallet; Web3AuthOptions({ required this.clientId, required this.redirectUrl, this.originData, this.authBuildEnv = BuildEnv.production, String? sdkUrl, this.storageServerUrl, this.sessionSocketUrl, this.citadelServerUrl, this.authConnectionConfig = const [], this.whiteLabel, String? dashboardUrl, this.accountAbstractionConfig, String? walletSdkUrl, this.sessionNamespace, this.includeUserDataInToken = true, this.chains, this.defaultChainId, this.enableLogging = false, this.sessionTime, required this.web3AuthNetwork, this.useSFAKey = false, this.walletServicesConfig, this.mfaSettings, this.wsEmbedDappClientId, this.useAAWithExternalWallet, }); } ``` ## Session management Control how long users stay authenticated and how sessions persist. The native SDKs store the session securely on the device (Android Keystore and iOS Keychain). **Key Configuration Options:** - `sessionTime` - Session duration in seconds. Controls how long users remain authenticated before needing to log in again. - Minimum: 1 second (`1`). - Maximum: 30 days (`86400 * 30`). - Default: 30 days (`30 * 86400`). When unset, the SDK uses the session time set in your dashboard project instead, if you configured one. Set `sessionTime` only when you want a different duration than the default or your dashboard setting. ```dart await Web3AuthFlutter.init(Web3AuthOptions( clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard dashboard web3AuthNetwork: Web3AuthNetwork.sapphire_mainnet, // or Web3AuthNetwork.sapphire_devnet sessionTime: 30 * 86400, // 30 days (in seconds) redirectUrl: redirectUrl, )); ``` ## Custom authentication methods Control the login options presented to your users. For detailed configuration options and implementation examples, see the [custom authentication](/embedded-wallets/sdk/flutter/advanced/custom-authentication/) section. ## UI customization Customize the brand experience by customizing the Web3Auth Login Screens to match your application's design. For complete customization options, refer to the [whitelabeling and UI customization](/embedded-wallets/sdk/flutter/advanced/whitelabel/) section. ## Multi-Factor Authentication (MFA) Add additional security layers to protect user accounts with two-factor authentication. See the [detailed configuration options and implementation examples](/embedded-wallets/sdk/flutter/advanced/mfa/). **Key Configuration Options:** - `mfaSettings` - Configure MFA settings for different authentication flows - `mfaLevel` - Control when users are prompted to set up MFA