README.mdx

title	Advanced configuration
sidebar_label	Overview
description	@web3auth/modal Advanced Configuration | Embedded Wallets

import TabItem from '@theme/TabItem' import Tabs from '@theme/Tabs' import Web3AuthOptions from '../../_common/_web3auth-options.mdx'

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 create a configuration object that is passed to the Web3AuthProvider. This consists of:

import { type Web3AuthContextConfig } from '@web3auth/modal/vue'
import { WEB3AUTH_NETWORK, type Web3AuthOptions } from '@web3auth/modal'

// focus-start
const web3AuthOptions: Web3AuthOptions = {
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID', // Pass your Web3Auth Client ID, ideally using an environment variable // Get your Client ID from MetaMask Developer Dashboard
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET, // or WEB3AUTH_NETWORK.SAPPHIRE_DEVNET
  // Core and advanced options go here
}
// focus-end

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions,
}

Web3AuthOptions

Session management

Control how long users stay authenticated and how sessions persist.

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: 7 days (86400 * 7).
• storageType - Storage location for authentication state. Options:
  • "local": Persists across browser tabs and browser restarts (localStorage)
  • "session": Persists only in current tab, cleared when tab closes (sessionStorage)

const web3AuthOptions = {
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID', // Pass your Web3Auth Client ID, ideally using an environment variable
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,

  // Session configuration
  sessionTime: 86400 * 7, // 7 days (in seconds)
  storageType: 'local', // 'local' (persistent across tabs) or 'session' (single tab only)
}

Multi-Factor Authentication

Add additional security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see Multi-Factor Authentication (MFA).

Key Configuration Options:

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

Custom authentication methods

Control the login options presented to your users and how they're displayed in the modal. For detailed configuration options and implementation examples, see the custom authentication section.

Key Configuration Options:

• modalConfig - Define which authentication methods are available and customize their appearance

UI customization

Customize the brand experience by customizing the Web3Auth Modal to match your application's design. For complete customization options, refer to the Whitelabeling & UI Customization section.

Key Configuration Options:

• uiConfig - Personalize the modal's look and feel with custom colors, logos, themes, and more
• modalConfig - Control the visibility and arrangement of authentication options

Smart accounts (account abstraction)

Improve user experience with gasless transactions and advanced account features. Learn more in the smart accounts documentation.

Key Configuration Options:

• accountAbstractionConfig - Fine-tune parameters for smart account implementation
• useAAWithExternalWallet - Enable account abstraction functionality even when users connect with external wallets

Wallet Services

Extend your application with enhanced wallet functionality. See the Wallet Services documentation for complete configuration options.

Key Configuration Options:

• walletServicesConfig - Integrate additional Wallet Services and features