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 com.web3auth.core.Web3Auth
import com.web3auth.core.types.Web3AuthOptions
import org.torusresearch.fetchnodedetails.types.Web3AuthNetwork

var web3Auth = Web3Auth(
  Web3AuthOptions(
    clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
    web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
    redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
  ),
  this
)

// Handle user signing in when app is in background
web3Auth.setResultUrl(intent?.data)

Web3AuthOptions​

The Web3Auth constructor takes a Web3AuthOptions object and an Android Context (usually the current activity) as input.

ParameterDescription
clientIdYour Embedded Wallets Client ID. You can get it from Embedded Wallets dashboard under project details. It's a mandatory field of type String
web3AuthNetworkDefines the Embedded Wallets Network. It's a mandatory field of type Web3AuthNetwork.
redirectUrlURL that Embedded Wallets will redirect API responses upon successful authentication from browser. It's a mandatory field of type String.
sessionTime?Session duration in seconds. Default is 30 days (86400 * 30), which is also the maximum. If you leave it unset, initialize() uses the session time configured in your dashboard project instead.
useSFAKey?Use SFA key to get single factor auth key. It's an optional field with default value as false. Useful for pre-generated wallets and SFA mode.
chains?Custom chain configuration for blockchain networks. It takes Chains as a value. See Chains configuration below.
defaultChainId?Default chain ID to use. It's an optional field with a default value of "0x1" (Ethereum mainnet). The first chain from the project config will be used if the project has chains configured.
enableLogging?Setting to true will enable logs. It's an optional field with default value as false.
authBuildEnv?Auth environment to use. Accepts BuildEnv.PRODUCTION (default), BuildEnv.STAGING, or BuildEnv.TESTING. Use PRODUCTION unless the MetaMask team instructs otherwise.

Session management​

Control how long users stay authenticated and how sessions persist. The session key is stored in the device's encrypted Keystore.

Key Configuration Options:

  • sessionTime - Session duration in seconds. Controls how long users remain authenticated before needing to sign in again.
    • Minimum: 1 second (1).
    • Maximum: 30 days (86400 * 30).
    • Default: 30 days (86400 * 30). If you leave sessionTime unset, initialize() uses the session time configured in your dashboard project instead.
var web3Auth = Web3Auth(
  Web3AuthOptions(
    clientId = "YOUR_WEB3AUTH_CLIENT_ID", // Pass over your Web3Auth Client ID from Developer Dashboard
    web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
    sessionTime = 86400 * 7, // 7 days (in seconds)
    redirectUrl = "{YOUR_APP_PACKAGE_NAME}://auth",
  ),
  this
)

Chains Configuration​

The chains parameter lets you specify a custom blockchain network for the SDK. When set, this chain is used by Wallet Services (showWalletUI, request) in addition to any chains configured in the project dashboard.

Chains Fields​

FieldTypeRequiredDescription
chainIdStringYesChain ID in hex format (for example, "0x1" for Ethereum mainnet, "0x89" for Polygon).
rpcTargetStringYesRPC endpoint URL for the chain.
chainNamespaceChainNamespaceNoNamespace of the chain. Accepts ChainNamespace.EIP155, SOLANA, or OTHER. Default is EIP155.
decimalsInt?NoNumber of decimals for the native token. Default is 18.
blockExplorerUrlString?NoURL of the block explorer for this chain.
displayNameString?NoHuman-readable name for the chain.
logoString?NoURL of the chain's logo image.
tickerString?NoTicker symbol for the native token (for example, "ETH").
tickerNameString?NoFull name of the native token (for example, "Ethereum").

Interface​

data class Chains(
    val chainNamespace: ChainNamespace = ChainNamespace.EIP155,
    val decimals: Int? = 18,
    val blockExplorerUrl: String? = null,
    val chainId: String,
    val displayName: String? = null,
    val logo: String? = null,
    val rpcTarget: String,
    val ticker: String? = null,
    val tickerName: String? = null,
)

Example​

val web3Auth = Web3Auth(
  Web3AuthOptions(
    clientId = "YOUR_WEB3AUTH_CLIENT_ID",
    web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
    redirectUrl = "YOUR_APP_SCHEME://auth",
    chains = Chains(
      chainId = "0x89",
      rpcTarget = "https://rpc.ankr.com/polygon",
      displayName = "Polygon Mainnet",
      ticker = "MATIC",
      tickerName = "Matic",
      blockExplorerUrl = "https://polygonscan.com"
    )
  ),
  this
)

Custom authentication methods​

Control the sign-in 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 Embedded Wallets sign-in screens to match your application's design. For complete customization options, refer to the Whitelabeling & UI Customization section.

Multi-Factor Authentication​

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

Key Configuration Options:

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

Wallet Services Configuration​

The walletServicesConfig parameter in Web3AuthOptions allows you to customize the behavior of the wallet UI (showWalletUI) and request signing (request). During initialize(), the SDK merges the Wallet UI settings from your dashboard into this config; values you set in code take precedence. For full configuration options, see the Smart Accounts section.

ParameterDescription
confirmationStrategy?Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy enum. Default is null, which uses the dashboard's confirmation modal setting, or DEFAULT if none is set.
whiteLabel?Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts WhiteLabelData as value.
enableKeyExport?Whether users can export their private key from the wallet UI. Default is null, which uses the dashboard's key export setting.
val web3Auth = Web3Auth(
  Web3AuthOptions(
    clientId = "YOUR_WEB3AUTH_CLIENT_ID",
    web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
    redirectUrl = "YOUR_APP_SCHEME://auth",
    walletServicesConfig = WalletServicesConfig(
      confirmationStrategy = ConfirmationStrategy.MODAL
    )
  ),
  this
)
On this page