Advanced configuration
The Embedded Wallets SDK offers configuration options to customize authentication flows, UI appearance, blockchain integrations, and security features for your dapp.
Configuration structure
Pass options to the Web3Auth constructor during setup:
import Web3Auth
web3Auth = try await Web3Auth(
options: Web3AuthOptions(
clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard
redirectUrl: "com.yourapp.bundleid://auth",
web3AuthNetwork: .SAPPHIRE_MAINNET // or .SAPPHIRE_DEVNET
)
)
Web3AuthOptions
The constructor takes a Web3AuthOptions struct as input.
Web3AuthOptions provides two public initializers:
Web3AuthOptions(clientId:web3AuthNetwork:redirectUrl:)sets only the three required values.- The full initializer accepts every option listed below. Swift requires labeled arguments in
declaration order, so pass
clientIdandredirectUrlfirst, and placeweb3AuthNetworkaftersessionTimeand beforeuseSFAKey. See the Struct tab for the exact order.
- Table
- Struct
Basic parameters:
| Parameter | Description |
|---|---|
clientId | Your Web3Auth Client ID from the Dashboard. It's a mandatory field of type String. |
redirectUrl | URL that Web3Auth will redirect API responses upon successful authentication. Use {bundleId}://auth. It's a mandatory field of type String. |
web3AuthNetwork | Web3Auth Network: .SAPPHIRE_MAINNET, .SAPPHIRE_DEVNET, .MAINNET, .TESTNET, .CYAN, .AQUA, or .CELESTE. Mandatory field of type Web3AuthNetwork. |
sessionTime? | Session duration in seconds. Default is nil, which uses the session time configured on the dashboard, or 30 days (86400 * 30) if the dashboard doesn't return one. Values above 30 days are clamped to 30 days. Accepts Int. |
useSFAKey? | Use SFA key to get single factor auth key. Default is false. Useful for wallet pre-generation and SFA mode. |
defaultChainId? | Default chain ID to use. Default is "0x1" (Ethereum mainnet). |
enableLogging? | Enable SDK logging. Default is false. |
Advanced parameters:
| Parameter | Description |
|---|---|
whiteLabel? | Whitelabel options for custom UI, branding, and translations. Takes WhiteLabelData as a value. |
authConnectionConfig? | Auth connection config for custom auth connections. Takes [AuthConnectionConfig] as a value. |
mfaSettings? | Configure MFA settings for authentication. Takes MfaSettings as a value. |
chains? | Custom chain configuration for blockchain networks. Takes [Chains] as a value. See Chains configuration below. |
walletServicesConfig? | Configuration for Wallet Services including whitelabel options. Takes WalletServicesConfig as a value. |
authBuildEnv? | Build environment of the Web3Auth services: .production, .staging, or .testing. Default is .production. Takes BuildEnv (also available as the Web3AuthBuildEnv type alias) as a value. |
originData? | Signed allowlist entries, as [String: String]. The SDK merges these with the signed URLs from your dashboard allowlist. |
includeUserDataInToken? | Whether to include user data in the ID token. Default is true. |
accountAbstractionConfig? | Smart account configuration as a JSON String. If you don't set it, the SDK uses the smart account configuration from the dashboard. |
useAAWithExternalWallet? | Whether to use smart accounts with external wallets in Wallet Services. If you don't set it, the SDK derives it from the dashboard smart account wallet scope. |
sessionNamespace? | Custom namespace for session storage. Takes String as a value. |
wsEmbedDappClientId? | Client ID passed to Wallet Services. Takes String as a value. |
sdkUrl? | Override for the Web3Auth auth service URL. The default is the URL for authBuildEnv. |
walletSdkUrl? | Override for the Wallet Services URL. The default is the URL for authBuildEnv. |
dashboardUrl? | Override for the account dashboard URL used by manageMFA. The default is the URL for authBuildEnv. |
storageServerUrl? | Override for the session storage server URL. The default is the URL for authBuildEnv. |
sessionSocketUrl? | Override for the session socket server URL. The default is the URL for authBuildEnv. |
citadelServerUrl? | Override for the token-based session (Citadel) server URL. The default is the URL for authBuildEnv. |
public struct Web3AuthOptions: Codable {
public init(
clientId: String,
redirectUrl: String,
originData: [String: String]? = nil,
authBuildEnv: BuildEnv? = .production,
sdkUrl: String? = nil,
storageServerUrl: String? = nil,
sessionSocketUrl: String? = nil,
citadelServerUrl: String? = nil,
authConnectionConfig: [AuthConnectionConfig]? = nil,
whiteLabel: WhiteLabelData? = nil,
dashboardUrl: String? = nil,
accountAbstractionConfig: String? = nil,
walletSdkUrl: String? = nil,
includeUserDataInToken: Bool? = true,
chains: [Chains]? = nil,
defaultChainId: String? = "0x1",
enableLogging: Bool? = false,
sessionTime: Int? = nil,
web3AuthNetwork: Web3AuthNetwork,
useSFAKey: Bool? = nil,
walletServicesConfig: WalletServicesConfig? = nil,
mfaSettings: MfaSettings? = nil,
sessionNamespace: String? = nil,
wsEmbedDappClientId: String? = nil,
useAAWithExternalWallet: Bool? = nil
)
public init(clientId: String, web3AuthNetwork: Web3AuthNetwork, redirectUrl: String)
}
Session management
Control how long users stay authenticated and how sessions persist. The SDK stores session data in the device's Keychain.
Key configuration options:
sessionTime- Session duration in seconds. Controls how long users remain authenticated before needing to sign in again.- Maximum: 30 days (
86400 * 30). Larger values are clamped to 30 days. - Default:
nil, which uses the session time configured in the dashboard, or 30 days if none is set.
- Maximum: 30 days (
web3Auth = try await Web3Auth(
options: Web3AuthOptions(
clientId: "YOUR_WEB3AUTH_CLIENT_ID", // Get your Client ID from Embedded Wallets dashboard
redirectUrl: "com.yourapp.bundleid://auth",
sessionTime: 86400 * 7, // 7 days (in seconds)
web3AuthNetwork: .SAPPHIRE_MAINNET
)
)
The SDK uses token-based sessions.
After sign-in, you can call getAccessToken,
getIdentityToken, and
refreshSession to work with the session tokens.
Chains configuration
The chains parameter lets you specify blockchain networks for Wallet Services (showWalletUI,
request).
If your project has chains configured in the dashboard, the SDK uses the dashboard chains for
Wallet Services.
The SDK uses chains from Web3AuthOptions only when the dashboard returns no chains.
Chains fields
| Field | Type | Required | Description |
|---|---|---|---|
chainId | String | Yes | Chain ID in hex format (for example, "0x1" for Ethereum mainnet, "0x89" for Polygon). |
rpcTarget | String | Yes | RPC endpoint URL for the chain. |
chainNamespace | ChainNamespace | No | Namespace of the chain. Only .eip155 is available. 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 (for example, "ETH"). |
tickerName? | String? | No | Full name of the native token (for example, "Ethereum"). |
Interface
public struct Chains: Codable {
public init(
chainNamespace: ChainNamespace = ChainNamespace.eip155,
decimals: Int? = 18,
blockExplorerUrl: String? = nil,
chainId: String,
displayName: String? = nil,
logo: String? = nil,
rpcTarget: String,
ticker: String? = nil,
tickerName: String? = nil
)
}
Example
web3Auth = try await Web3Auth(
options: Web3AuthOptions(
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
redirectUrl: "com.yourapp.bundleid://auth",
chains: [
Chains(
blockExplorerUrl: "https://polygonscan.com",
chainId: "0x89",
displayName: "Polygon Mainnet",
rpcTarget: "https://rpc.ankr.com/polygon",
ticker: "POL",
tickerName: "Polygon Ecosystem Token"
)
],
defaultChainId: "0x89",
web3AuthNetwork: .SAPPHIRE_MAINNET
)
)
Wallet Services configuration
The walletServicesConfig parameter in Web3AuthOptions customizes the behavior of the wallet
UI (showWalletUI) and request signing (request).
For full configuration options, see the Wallet Services section.
| Parameter | Description |
|---|---|
confirmationStrategy? | Controls how transaction confirmations are displayed. Accepts ConfirmationStrategy. Default is .defaultStrategy. |
whiteLabel? | Whitelabel settings specific to the Wallet Services UI. When set, merged with the project-level whitelabel config. Accepts WhiteLabelData. |
enableKeyExport? | Whether users can export their private key from the Wallet Services UI. Accepts Bool. |
web3Auth = try await Web3Auth(
options: Web3AuthOptions(
clientId: "YOUR_WEB3AUTH_CLIENT_ID",
redirectUrl: "com.yourapp.bundleid://auth",
web3AuthNetwork: .SAPPHIRE_MAINNET,
walletServicesConfig: WalletServicesConfig(
confirmationStrategy: .modal
)
)
)
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 Embedded Wallets sign-in screens to match your dapp's design. For complete customization options, see Whitelabeling and UI customization.
Multi-Factor Authentication
Add security layers to protect user accounts with two-factor authentication. For detailed configuration options and implementation examples, see Multi-Factor Authentication.
Key configuration options:
mfaSettings- Configure MFA settings for different authentication flowsmfaLevel- Control when users are prompted to set up MFA