Skip to main content

Web3Auth PnP Web SDK v10 Migration Guide

This guide will help you upgrade your Web3Auth PnP SDK integration from v9 (whether you were using the Modal or the @web3auth/no-modal SDK) to the unified Web3Auth PnP Web SDK v10.

Version 10 consolidates into a single powerful SDK that centralizes configuration in the Dashboard, eliminates frontend adapter complexity, and provides seamless custom UI support.

Why these changes?​

Web3Auth v9 offered separate modal and non-modal SDKs for flexibility. V10 consolidates these into a unified SDK that simplifies integration patterns, reduces boilerplate, and centralizes configuration.

Building on the foundation of v9, key areas of evolution in v10 include:

  • A Unified & Versatile SDK (@web3auth/modal): Consolidates all functionalities into a single SDK supporting both pre-built modal UIs and custom user interfaces with one consistent API.
  • Dashboard-Centric Configuration: Login methods, connections (formerly verifiers), Smart Account settings, and chain configurations are now managed through the Web3Auth Developer Dashboard.
  • Streamlined Login & Connection Management: Moves to a declarative approach with login methods defined on the dashboard and more direct client-side connection calls.
  • Automated Blockchain Setup: Standard blockchains no longer require manual chainConfig and privateKeyProvider setup as these are handled automatically via dashboard settings.
  • Integrated Smart Account Functionality: Smart Account configuration is managed on the dashboard with functionality built directly into the main SDK, eliminating separate provider packages.
  • Simplified Multi-Factor Authentication (MFA): MFA setup is streamlined with key settings configured directly during SDK initialization.
  • Modernized Framework Support: React and Vue applications now use streamlined hooks/composables with automatic SDK initialization.

The result is a cleaner, more declarative, and more maintainable integration experience—especially for teams maintaining apps across multiple auth flows and chains, all using one SDK.

Installation​

Install the latest v10 unified SDK package. Depending on your framework, you'll primarily use one of the following:

npm install @web3auth/modal

General Migration Points (Applicable to All Frameworks)​

1. Centralized Chain Configuration​

import { Web3Auth } from "@web3auth/modal";
import { EthereumPrivateKeyProvider } from "@web3auth/ethereum-provider";
import { getEvmChainConfig } from "@web3auth/base";

const chainConfig = getEvmChainConfig(1, WEB3AUTH_CLIENT_ID);

const ethereumPrivateKeyProvider = EthereumPrivateKeyProvider({
  config: { chainConfig },
});

const web3auth = new Web3Auth({
  clientId: WEB3AUTH_CLIENT_ID, // Get your Client ID from the Web3Auth Dashboard
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  privateKeyProvider: ethereumPrivateKeyProvider,
});

In v10, chain configurations for standard EVM chains and passing of private key providers are not needed anymore. You will be able to switch chains in your dapp among the chains you've toggled on from the Web3Auth Developer Dashboard.

Chains on Dashboard

This means the chainConfig and privateKeyProvider properties in Web3AuthOptions are not needed for v10 if you're using standard chains configured on your dashboard.

You can also add custom chains on the dashboard and use them in your dapp.

2. Multi-Factor Authentication (MFA)​

MFA configuration has been streamlined. In v9, both mfaLevel and detailed factor configurations (mfaSettings) were set within the @web3auth/auth-adapter. This has changed in v10.

MFA factor settings and level configuration have moved from AuthAdapter to Web3AuthOptions:

import { AuthAdapter } from "@web3auth/auth-adapter";

const authAdapter = new AuthAdapter({
  loginSettings: {
    mfaLevel: "mandatory", // e.g., default, optional, mandatory, none
  },
  adapterSettings: {
    mfaSettings: {
      deviceShareFactor: { enable: true, priority: 1, mandatory: true },
      // ... other factors
    },
  },
});

import { MFA_FACTOR, MFA_LEVELS, WEB3AUTH_NETWORK, type Web3AuthOptions } from "@web3auth/modal";

const web3AuthOptions: Web3AuthOptions = {
  clientId: "YOUR_CLIENT_ID",
  web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_MAINNET,
  mfaLevel: MFA_LEVELS.MANDATORY,
  mfaSettings: {
    // Configure individual factors here
    [MFA_FACTOR.DEVICE]: {
      enable: true,
      priority: 1,
      mandatory: true,
    },
    [MFA_FACTOR.BACKUP_SHARE]: {
      enable: true,
      priority: 2,
      mandatory: true,
    },
    // ... other factors
  },
};

Key Changes:

  • Individual MFA Factor Settings: Move from AuthAdapter.adapterSettings.mfaSettings to Web3AuthOptions.mfaSettings
  • Factor Keys: Change from descriptive strings (e.g., deviceShareFactor) to enum values (e.g., [MFA_FACTOR.DEVICE])
  • MFA Level: Move from AuthAdapter.loginSettings.mfaLevel to Web3AuthOptions.mfaLevel

3. useCoreKitKey Renamed to useSFAKey​

Note that the parameter useCoreKitKey (v9) has been renamed to useSFAKey (v10). This is a breaking change if you were using it to get CoreKit keys. This parameter is part of the Web3AuthOptions object.

const web3AuthOptions: Web3AuthOptions = {
  useCoreKitKey: true,
  useSFAKey: true,
};

4. authenticateUser() Renamed to getIdentityToken()​

In v9, the method web3auth.authenticateUser() was used to retrieve the user's ID token. In v10, this method has been renamed to web3auth.getIdentityToken().

The purpose and the structure of the returned ID token (a JWT containing user information) remain the same. This is primarily a naming convention change.

const userAuthInfo = await web3auth.authenticateUser();
const userAuthInfo = await web3auth.getIdentityToken(); // Returns { idToken: string }

const idToken = userAuthInfo.idToken;

Wallet Services: If you used the @web3auth/wallet-services-plugin in v9, see the 🛠️ Wallet Services Migration Guide for migrating to the built-in integration.

Additional Migration Guides​

For specific functionality or frameworks, refer to these dedicated migration guides:

📋 Whitelabeling and UI Customization: If you had whitelabeling configurations (uiConfig, modalConfig, or AuthAdapter whitelabel settings) in v9, see the Whitelabeling Migration Guide for detailed steps.

🔧 Smart Account Functionality: If you used Smart Accounts in v9 with @web3auth/account-abstraction-provider, see the Smart Account Migration Guide for the new dashboard-centric approach.

🔐 Custom Authentication: If you used custom verifiers or aggregate verifiers in v9, see the Custom Authentication Migration Guide for migrating to the new Connections system.

⚛️ React & Vue Applications: If you're using React or Vue with Web3Auth, see the React & Vue Migration Guide for framework-specific migration steps including hooks, composables, and provider configurations.

Further Reading​