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:

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 an object with Web3AuthOptions as input.

• Basic Parameters
• Advanced Parameters
• Interface

Parameter	Description
context	Android context to launch Web-based authentication, usually is the current activity. It's a mandatory field, and accepts android.content.Context as a value.
clientId	Your Web3Auth Client ID. You can get it from Web3Auth Dashboard under project details. It's a mandatory field of type String
web3AuthNetwork	Defines the Web3Auth Network. It's a mandatory field of type Web3AuthNetwork.
redirectUrl	URL that Web3Auth will redirect API responses upon successful authentication from browser. It's a mandatory field of type String.
sessionTime?	It allows developers to configure the session management time. Session Time is in seconds, default is 86400 * 30 seconds (30 days). sessionTime can be max 30 days
useSFAKey?	Use SFA Key to get single factor auth key. It's an optional field with default value as false. Useful for Wallet Pregeneration 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.

Parameter	Description
whiteLabel?	WhiteLabel options for web3auth. It helps you define custom UI, branding, and translations for your brand app. It takes WhiteLabelData as a value.
authConnectionConfig?	Auth connection config for the custom auth connections. It takes List<AuthConnectionConfig> as a value.
mfaSettings?	Allows developers to configure the MFA settings for authentication. It takes MfaSettings as a value.
walletServicesConfig?	Configuration for wallet services including whitelabel options. It takes WalletServicesConfig as a value.

data class Web3AuthOptions(
    val clientId: String,
    var redirectUrl: String,
    @SerializedName("network") val web3AuthNetwork: Web3AuthNetwork,
    @SerializedName("buildEnv") var authBuildEnv: BuildEnv = BuildEnv.PRODUCTION,
    var whiteLabel: WhiteLabelData? = null,
    var authConnectionConfig: List<AuthConnectionConfig>? = emptyList(),
    val useSFAKey: Boolean? = false,
    var chains: Chains? = null,
    var mfaSettings: MfaSettings? = null,
    val sessionTime: Int = 30 * 86400,
    val walletServicesConfig: WalletServicesConfig? = null,
    var defaultChainId: String? = "0x1",
    var enableLogging: Boolean = false
)

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 log in again.
  • Minimum: 1 second (1).
  • Maximum: 30 days (86400 * 30).
  • Default: 30 days (86400 * 30).

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

Field	Type	Required	Description
chainId	String	Yes	Chain ID in hex format (e.g. "0x1" for Ethereum mainnet, "0x89" for Polygon).
rpcTarget	String	Yes	RPC endpoint URL for the chain.
chainNamespace	ChainNamespace	No	Namespace of the chain. Accepts ChainNamespace.EIP155, SOLANA, or OTHER. Default is EIP155.
decimals	Int?	No	Number of decimals for the native token. Default is 18.
blockExplorerUrl	String?	No	URL of the block explorer for this chain.
displayName	String?	No	Human-readable name for the chain.
logo	String?	No	URL of the chain's logo image.
ticker	String?	No	Ticker symbol for the native token (e.g. "ETH").
tickerName	String?	No	Full name of the native token (e.g. "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 login options presented to your users. For detailed configuration options and implementation examples, see the custom authentication section.

UI customization

Create a seamless brand experience by customizing the Embedded Wallets login 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). For full configuration options, see the Smart Accounts section.

Parameter	Description
confirmationStrategy?	Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy enum. Default is ConfirmationStrategy.DEFAULT.
whiteLabel?	Whitelabel settings specific to the wallet services UI. When set, merged with the project-level whitelabel config. Accepts WhiteLabelData as value.

val web3Auth = Web3Auth(
  Web3AuthOptions(
    clientId = "YOUR_WEB3AUTH_CLIENT_ID",
    web3AuthNetwork = Web3AuthNetwork.SAPPHIRE_MAINNET,
    redirectUrl = "YOUR_APP_SCHEME://auth",
    walletServicesConfig = WalletServicesConfig(
      confirmationStrategy = ConfirmationStrategy.MODAL
    )
  ),
  this
)