# Advanced configuration

> @web3auth/modal Advanced Configuration | Embedded Wallets

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 create a configuration object that is passed to the `Web3AuthProvider`. This consists of:

```tsx title="web3authContext.tsx"

// focus-start
const web3AuthOptions: Web3AuthOptions = {
  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
}
// focus-end

const web3AuthContextConfig: Web3AuthContextConfig = {
  web3AuthOptions,
}
```

### `Web3AuthOptions`

<Tabs
  defaultValue="basic"
  values={[
    { label: "Basic parameters", value: "basic" },
    { label: "Advanced parameters", value: "advanced" },
    { label: "Interface", value: "interface" },
  ]}
>

<TabItem value="basic">

| 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.                                                                                                         |

</TabItem>

<TabItem value="advanced">

| 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.                                                           |

</TabItem>

<TabItem value="interface">

```tsx
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
}
```

</TabItem>

</Tabs>

## 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 log 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)

```tsx
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

Add additional security layers to protect user accounts with two-factor authentication. For detailed
configuration options and implementation examples, see [Multi-Factor Authentication (MFA)](./mfa.mdx).

**Key Configuration Options:**

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

## Custom authentication methods

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

**Key Configuration Options:**

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

## 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 & UI Customization](./whitelabel.mdx) 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)

Improve user experience with gasless transactions and advanced account features. Learn more in the
[smart accounts](./smart-accounts.mdx) 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

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

**Key Configuration Options:**

- `walletServicesConfig` - Integrate additional Wallet Services and features