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 { Web3Auth, WEB3AUTH_NETWORK } from '@web3auth/modal'

const web3auth = new Web3Auth({
  clientId: 'YOUR_WEB3AUTH_CLIENT_ID',
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
})

await web3auth.init()

`Web3AuthOptions`

Basic parameters
Advanced parameters
Interface

Parameter	Description
`clientId`	(Mandatory) Client ID, available from the Embedded Wallets dashboard.
`web3AuthNetwork`	(Mandatory) Web3Auth network to use for the session and the issued `idToken`, for example `sapphire_mainnet` or `sapphire_devnet`.
`enableLogging?`	Setting to true enables logs. Default is false.
`sessionTime?`	Session Time (in seconds) for `idToken` issued by Web3Auth for server side verification. If not set, the SDK uses the session time configured on the dashboard, then falls back to 30 days (30 * 86400). Max value can be 30 days (86400 * 30) and min can be 1 sec (1)
`useSFAKey?`	Uses Single Factor Auth SDK key with Web3Auth provider. Default is false.
`storage?`	Custom storage adapters for auth tokens (`sessionId`, `accessToken`, `refreshToken`, `idToken`). Default is `localStorage`-based adapters.
`cookieOptions?`	Cookie configuration used when storage adapters are cookie-based.
`defaultChainId?`	Default chain ID to use. Your first chain will be used as default.
`multiInjectedProviderDiscovery?`	Whether to enable discovery of injected wallets in the browser. Default is true.

Parameter	Description
`chains?`	Optional in-code chain list. By default, chains are fetched from the dashboard. Pass `chains` only for custom RPC, demos, or overrides.
`uiConfig?`	(Fetched automatically from dashboard) Config for configuring UI display properties.
`modalConfig?`	Helps you customize the modal UI elements and authentication methods.
`accountAbstractionConfig?`	(Fetched automatically from Dashboard) Account abstraction config for your chain namespace.
`useAAWithExternalWallet?`	(Fetched automatically from Dashboard) Whether to use AA with external wallet.
`walletServicesConfig?`	(Fetched automatically from Dashboard) Configure any parameter related to Wallet Services plugin
`ssr?`	Whether to enable SSR mode.
`mfaSettings?`	MFA settings for the auth connector.
`mfaLevel?`	MFA level for the auth connector.
`privateKeyProvider?`	Private key provider for your chain namespace.
`initialAuthenticationMode?`	Initial authentication mode: `connect-and-sign` (default) or `connect-only`.
`disableAnalytics?`	Whether to disable SDK analytics. Default is false.
`connectors?`	Additional wallet connectors to use.
`plugins?`	Additional plugins to use.

export interface Web3AuthOptions extends IWeb3AuthCoreOptions {
  /**
   * Config for configuring modal ui display properties
   */
  uiConfig?: Omit<UIConfig, 'connectorListener'>
  /**
   * Config for configuring modal ui display properties
   */
  modalConfig?: ConnectorsModalConfig
}

export interface IWeb3AuthCoreOptions {
  /**
   * Client id for web3auth.
   * You can obtain your client id from the web3auth developer dashboard.
   * You can set any random string for this on localhost.
   */
  clientId: string
  /**
   * multiple chain configurations,
   * only provided chains will be used
   */
  chains?: CustomChainConfig[]
  /**
   * default chain Id to use
   */
  defaultChainId?: string
  /**
   * setting to true will enable logs
   *
   * @defaultValue false
   */
  enableLogging?: boolean
  /**
   * Custom storage adapters for auth tokens (sessionId, accessToken, refreshToken, idToken).
   * @defaultValue localStorage-based adapters
   */
  storage?: StorageConfig
  /**
   * Cookie configuration used when storage adapters are cookie-based.
   */
  cookieOptions?: CookieOptions
  /**
   * sessionTime (in seconds) for idToken issued by Web3Auth for server side verification.
   * @defaultValue dashboard session time, otherwise 30 * 86400
   *
   * Note: max value can be 30 days (86400 * 30) and min can be  1 sec (1)
   */
  sessionTime?: number
  /**
   * Web3Auth Network to use for the session.
   */
  web3AuthNetwork: WEB3AUTH_NETWORK_TYPE
  /**
   * Uses core-kit key with web3auth provider
   * @defaultValue false
   */
  useSFAKey?: boolean
  /**
   * Whitelabel options for web3auth
   */
  uiConfig?: UIConfig
  /**
   * Account abstraction config for your chain namespace
   */
  accountAbstractionConfig?: AccountAbstractionMultiChainConfig
  /**
   * Whether to use AA with external wallet
   */
  useAAWithExternalWallet?: boolean
  /**
   * Connectors to use
   */
  connectors?: ConnectorFn[]
  /**
   * Plugins to use
   */
  plugins?: PluginFn[]
  /**
   * Whether to enable multi injected provider discovery
   * @defaultValue true
   */
  multiInjectedProviderDiscovery?: boolean
  /**
   * Wallet services config
   */
  walletServicesConfig?: WalletServicesConfig
  /**
   * Private key provider for xrpl cases
   */
  privateKeyProvider?: IBaseProvider<string>
  /**
   * Whether to enable SSR mode
   *
   * @defaultValue false
   */
  ssr?: boolean
  /**
   * Build environment for Auth connector
   * @internal
   * @defaultValue BUILD_ENV.PRODUCTION
   */
  authBuildEnv?: BUILD_ENV_TYPE
  /**
   * MFA settings for the auth connector
   */
  mfaSettings?: MfaSettings
  /**
   * MFA level for the auth connector
   */
  mfaLevel?: MfaLevelType
  /**
   * Initial authentication mode for the auth connector.
   * @defaultValue "connect-and-sign"
   */
  initialAuthenticationMode?: ConnectorInitialAuthenticationModeType
  /**
   * Whether to disable analytics
   * @defaultValue false
   */
  disableAnalytics?: boolean
}