> For the complete documentation index, see [llms.txt](/llms.txt).

# 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[​](#configuration-structure "Direct link to Configuration structure")

When setting up Embedded Wallets, you'll pass in the options to the constructor. This consists of:

```
import { Component } from "@angular/core";
import { Web3Auth, WEB3AUTH_NETWORK } from "@web3auth/modal";

const web3auth = new Web3Auth({
  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
});

@Component({
  selector: "app-root",
  templateUrl: "./app.component.html",
  styleUrls: ["./app.component.css"],
})
export class AppComponent {

  async ngOnInit() {
    const init = async () => {
      await web3auth.init();
    };

    init();
  }
  ...
}

```

### `Web3AuthOptions`[​](#web3authoptions "Direct link to web3authoptions")

- Basic parameters
- Advanced parameters
- Interface

| Parameter                       | Description                                                                                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| clientId                        | (Mandatory) Client ID, available from the [Embedded Wallets dashboard](https://developer.metamask.io).                                                                               |
| web3AuthNetwork                 | (Mandatory) Web3Auth network to use for the session and the issued idToken. Default is sapphire_mainnet.                                                                             |
| enableLogging?                  | Setting to true enables logs. Default is false.                                                                                                                                      |
| sessionTime?                    | Session Time (in seconds) for idToken issued by Web3Auth for server side verification. Default is 7 days (7 * 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.                                                                                                            |
| storageType?                    | Setting to local persists social login session across browser tabs. Default is local.                                                                                                |
| 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?                   | (Fetched automatically from dashboard) Multiple chain configurations, only provided chains will be used. |
| 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.                                                           |

```
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
  /**
   * setting to "local" will persist social login session across browser tabs.
   *
   * @defaultValue "local"
   */
  storageType?: 'session' | 'local' | 'cookies'
  /**
   * sessionTime (in seconds) for idToken issued by Web3Auth for server side verification.
   * @defaultValue 7 * 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, mpc 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
}

```

## Session management[​](#session-management "Direct link to 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 sign 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[​](#multi-factor-authentication "Direct link to 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](/embedded-wallets/sdk/js/advanced/mfa/)section.

**Key Configuration Options:**

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

## Custom authentication methods[​](#custom-authentication-methods "Direct link to Custom authentication methods")

Control the sign-in options presented to your users and how they're displayed in the modal. For detailed configuration options and implementation examples, see the [custom authentication](/embedded-wallets/sdk/js/advanced/custom-authentication/) section.

**Key Configuration Options:**

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

## UI customization[​](#ui-customization "Direct link to UI customization")

Create a seamless brand experience by customizing the Web3Auth Modal to match your application's design. For complete customization options, refer to the [Whitelabeling and UI Customization](/embedded-wallets/sdk/js/advanced/whitelabel/) 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)[​](#smart-accounts-account-abstraction "Direct link to Smart accounts (account abstraction)")

Improve user experience with gasless transactions and advanced account features. Learn more in the [smart accounts](/embedded-wallets/sdk/js/advanced/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[​](#wallet-services "Direct link to Wallet Services")

Extend your application with enhanced wallet functionality. See the [Wallet Services](/embedded-wallets/sdk/js/advanced/wallet-services/) documentation for complete configuration options.

**Key Configuration Options:**

- `walletServicesConfig` - Integrate additional Wallet Services and features