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 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:

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

ParameterDescription
clientIdYour Web3Auth Client ID from the dashboard. Mandatory String.
web3AuthNetworkWeb3Auth Network: sapphire_mainnet, sapphire_devnet, mainnet, cyan, aqua, or testnet. Mandatory Web3AuthNetwork.
redirectUrlURL 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<AuthConnectionConfig> as a value.
chains?Chain configuration for Wallet Services and signing. Takes List<Chains> 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<String, String> 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.

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.

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

Key Configuration Options:

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