Skip to main content

Using PnP Web Modal SDK

Once you've installed and successfully initialized Web3Auth, you can use it to authenticate your users. Further, you can use the native provider given by Web3Auth to connect the users to the respective blockchain network.

Natively, the instance of Web3Auth (referred to as web3auth in our examples) returns the following functions:

  • connect() - Showing the Modal and Logging in the User
  • getUserInfo() - Getting the User's Information
  • enableMFA() - Enable Multi Factor Authentication for the user
  • manageMFA() - Redirect the user to manage their MFA settings in the Web3Auth Account Dashboard
  • authenticateUser() - Getting the idToken from Web3Auth
  • addChain() - Add chain config details to the connected adapter.
  • switchChain() - Switch chain as per chainId already added to chain config.
  • logout() - Logging out the User

Additionally the following methods are available to get information about the current state of the instance:

  • connected - Returns true or false depending on whether the user is connected or not.
  • status - Returns the current status of the web3auth instance.
  • provider - Returns the currently connected provider to the web3auth instance.
  • connectedAdapterName - Returns the currently connected provider to the web3auth instance.

Finally, with the Wallet Services Plugin, you can enable additional functionalities like:

  • showCheckout() - Initiate Topup for the user.
  • showWalletConnectScanner() - Show WalletConnect QR Code Scanner.
  • showWalletUI() - Show Embedded Wallet UI.
  • showSwap() - Show Swap UI.
  • showTransactionConfirmation() - Show Transaction Confirmation UI.

Logging in the User​

You can show the modal in the browser by calling connect() function on web3auth instance. Your user can choose their preferred login method and access your application.

await web3auth.connect();

Returns​

connect(): Promise<IProvider | null>;
  • On successful login, the connect() function returns a IProvider instance. This instance contains the respective provider corresponding to your selected blockchain. You can use this provider to connect your user to the blockchain and make transactions.
  • On unsuccessful login, this function will return a null value.
tip

Read more about connecting your users with the selected blockchain in the Providers SDK Reference.

Check if the user is connected​

connected​

You can check if the user is connected to the blockchain by calling the connected method on the web3auth instance. This property method a boolean value.

const isConnected = web3auth.connected;

Returns​

connected: boolean;
tip

If you're using the uxMode: "redirect" option within your configuration, you need to check this event to handle the logging in implicitly. This is because, when redirected to a different application, the app state is not updated as per the login status.

Using this method, you can check if the user is connected and update the app state accordingly within the constructor.

Check which adapter is connected​

connectedAdapterName​

This function gives you the name of the connected adapter. This can be used to check which adapter is connected to the user.

const adapter = web3auth.connectedAdapterName;

Returns​

connectedAdapterName: WALLET_ADAPTER_TYPE | null;

export type WALLET_ADAPTER_TYPE = (typeof WALLET_ADAPTERS)[keyof typeof WALLET_ADAPTERS];

export declare const WALLET_ADAPTERS: {
  AUTH: string;
  WALLET_CONNECT_V2: string;
  SFA: string;
  TORUS_SOLANA: string;
  TORUS_EVM: string;
  COINBASE: string;
};
  • If a user is connected, it will return the name of the adapter via which the login has happened.
  • If connecting via MIPD (EIP6163) in default evm/ solana adapters, it will return the name of the wallet connected.
  • If no user is connected, this function will return a null value.

Get the connected provider​

provider​

Returns the private key provider connected to the web3auth instance.

Returns​

provider: IProvider | null;
  • If a user is connected, it will return the provider instance connected to the user.
  • If no user is connected, however, the initialisation of the web3auth instance is done, it will return the provider instance, however the provider cannot be used for any operations.
  • If no user is connected and the web3auth instance is not initialised, it will return a null value.
note

To know more in-depth about providers, have a look at the Providers reference.

Know the current status of the instance​

status​

Returns the current status of the web3auth instance.

const status = web3auth.status;

An adapter emits certain events like CONNECTED, CONNECTING and DISCONNECTED etc during login lifecycle of a user. Knowing to events help you trigger responses based on the status of the connection of the user. For example, you can use this to show an error message, if the user is not connected to the network.

Web3Auth provides the following lifecycle event to check the login status:

EventDescription
NOT_READYTriggered when the adapter is not ready.
READYTriggered when the adapter is ready.
CONNECTINGTriggered when the user is connecting to the wallet.
CONNECTEDTriggered when the user is connected to the wallet.
ERROREDTriggered when an error occurs during the login lifecycle.

Get User's Information​

getUserInfo()​

You can get the information about connected user by calling getUserInfo() function.

note

This function will only return information based on the connected adapter. These details are not stored anywhere and are fetched from the adapter during the connection and remain in the session.

await web3auth.getUserInfo();

Returns​

VariableTypeDescription
emailstringEmail of the user.
namestringName of the user.
profileImagestringProfile image of the user.
aggregateVerifierstringAggregate verifier of the user.
verifierstringVerifier of the user.
verifierIdstringVerifier ID of the user.
typeOfLoginstringType of login provider.
dappSharestringDapp share of the user.
idTokenstringToken issued by Web3Auth.
oAuthIdTokenstringToken issued by OAuth provider. Will be available only if you are using custom verifiers.
oAuthAccessTokenstringAccess Token issued by OAuth provider. Will be available only if you are using custom verifiers.
appStatestringApp state of the user.
touchIDPreferencestringTouch ID preference of the user.
isMfaEnabledbooleanWhether Multi Factor Authentication is enabled for the user.

Sample Response​

{
  "email": "john@gmail.com",
  "name": "John Dash",
  "profileImage": "https://lh3.googleusercontent.com/a/Ajjjsdsmdjmnm...",
  "aggregateVerifier": "tkey-google-lrc",
  "verifier": "torus",
  "verifierId": "john@gmail.com",
  "typeOfLogin": "google",
  "dappShare": "<24 words seed phrase>", // will be sent only incase of custom verifiers
  "idToken": "<jwtToken issued by Web3Auth>",
  "oAuthIdToken": "<jwtToken issued by OAuth Provider>", // will be sent only incase of custom verifiers
  "oAuthAccessToken": "<accessToken issued by OAuth Provider>" // will be sent only incase of custom verifiers
}

Enable Multi Factor Authentication (MFA)​

enableMFA()​

You can enable Multi Factor Authentication for the user by calling the enableMFA() function. This function will trigger a redirect to the MFA setup page, where the user will be asked to login again and set up the MFA Methods according to the configuration set in the web3auth instance.

await web3auth.enableMFA();

Interface​

enableMFA<T>(loginParams?: T): Promise<void>;

Manage Multi Factor Authentication (MFA)​

manageMFA()​

You can redirect users to the Web3Auth Account Dashboard to manage their MFA settings by calling the manageMFA() function. This method ensures that identity details are injected into the dashboard internally for custom verifier-based dApps. In order to see what's present on the account dashboard, please refer to the Account Dashboard.

await web3auth.manageMFA();

Interface​

manageMFA<T>(loginParams?: T): Promise<void>;
  • loginParams (optional): Optional parameters to include during the MFA management process.
  • Returns: A Promise<void> indicating successful redirection to the Account Dashboard.
tip

If MFA is not already enabled, the manageMFA() method will throw an error. Ensure you use enableMFA() before calling manageMFA().

If your dApp uses default verifiers, users can directly log in to the Account Dashboard to manage MFA. For custom verifier-based dApps, the manageMFA() method must be used.

Get idToken for Backend Verification​

authenticateUser()​

You can get the idToken from Web3Auth by calling authenticateUser() function.

note

This function will only return information based on the connected adapter. These details are not stored anywhere and are fetched from the adapter during the connection and remain in the session.

await web3auth.authenticateUser();

Returns​

ParameterTypeDescription
iatnumberThe "iat" (issued at) claim identifies the time at which the JWT was issued.
audstringThe "aud" (audience) claim identifies the recipients that the JWT is intended for. (Here, it's the dapp client_id)
issstringThe "iss" (issuer) claim identifies who issued the JWT. (Here, it's Web3Auth https://api.openlogin.com/)
emailstringThe email address of the user (optional)
namestringThe name of the user (optional)
profileImagestringThe profile image of the user (optional)
verifierstringWeb3auth's verifier used while user login
verifierIdstringUnique user id given by OAuth login provider
aggregateVerifierstringName of the verifier if you are using a single id verifier (aggregateVerifier) (optional)
expnumberThe "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.
walletsarraylist of wallets for which this token is issued:
  • curve "secp256k1" (default) or "ed25519"
    You can specify which curve you want use for the encoded public key in the login parameters
  • type "web3auth_key" incase of social logins
  • public_key compressed public key derived based on the specified curve

Sample Response​

{
  "iat": 1655835494,
  "aud": "BCtbnOamqh0cJFEUYA0NB5YkvBECZ3HLZsKfvSRBvew2EiiKW3UxpyQASSR0artjQkiUOCHeZ_ZeygXpYpxZjOs",
  "iss": "https://api.openlogin.com/",
  "email": "xyz@xyz.com",
  "name": "John Doe",
  "profileImage": "https://lh3.googleusercontent.com/a/AATXAJx3lnGmHiM4K97uLo9Rb0AxOceH-dQCBSRqGbck=s96-c",
  "verifier": "torus",
  "verifierId": "xyz@xyz.com",
  "aggregateVerifier": "tkey-google-lrc",
  "exp": 1655921894,
  "wallets": [
    {
      "public_key": "035143318b83eb5d31611f8c03582ab1200494f66f5e11a67c34f5581f48c1b70b",
      "type": "web3auth_key",
      "curve": "secp256k1"
    }
  ]
}

Add EVM Blockchain to Instance​

addChain()​

To add a chain config to a connected adapter, you need to call addChain() function. This function helps you add the chain config by taking the following parameter:

VariableDescription
chainConfigCustomChainConfig for the chain you want to add.
await web3auth.addChain({
  chainId: "0xaa36a7",
  displayName: "Ethereum Sepolia",
  chainNamespace: CHAIN_NAMESPACES.EIP155,
  tickerName: "Sepolia",
  ticker: "ETH",
  decimals: 18,
  rpcTarget: "https://rpc.sepolia.org",
  blockExplorerUrl: "https://sepolia.etherscan.io",
  logo: "https://images.toruswallet.io/eth.svg",
  isTestnet: true,
});

Switch to an EVM Blockchain​

switchChain()​

To switch the Chain to the added chain config, you need to call switchChain() function. This function takes the following parameter:

VariableDescription
{ chainId: "0xaa36a7" }chainId of the added chain config, e.g { chainId: "0xaa36a7" }
await web3auth.switchChain({ chainId: "0xaa36a7" });

Logging out the User​

web3auth.logout()​

You can disconnect from connected wallet using logout function.

await web3auth.logout();

Type Reference​

logout(options?: { cleanup: boolean; }): Promise<void>;

Connecting to a Blockchain​

For Connecting to Blockchain and making RPC calls within your dApp, you can use the IProvider instance returned while logging in the user. This instance gives you the respective provider for your selection of blockchain. This provider can be used to interact with the connected chain using exposed functions within the provider.

Web3Auth is chain agnostic, ie. be it any chain you're connecting to, you can use Web3Auth to connect to it. You can use the EVM or Solana provider, that contain the native functions to connect to the blockchain or use the private key directly to connecting to the respective blockchain.

Currently web3auth supports providers for both EVM and Solana chains. For other chains, one can easily get the private key from the base provider from Web3Auth.

tip

Checkout the Providers SDK Reference to learn more.

Wallet Services Plugin Methods​

You can use the Wallet Services Plugin to enable additional functionalities like showing the Wallet UI Screen, Wallet Connect Scanner, and initiating topup for the user.

tip

Learn more about the Wallet Services Plugin in the Wallet Services SDK Reference.

Show WalletConnect Scanner​

You can use the showWalletConnectScanner function to show the Wallet Connect Scanner, and connect with dApps having Wallet Connect login option. This is useful for interoperability with dApps having Wallet Connect login option. Learn more about showWalletConnectScanner.

Fiat On Ramp​

You can use the showCheckout function to show the TopUp modal, allowing users to select their local currency and specify the token to top up their wallet. Learn more about showCheckout.

Embedded Wallet UI​

You can use the showWalletUI function to show the templated wallet UI services. Learn more about showWalletUI.

Swap Screen​

You can use the showSwap function to show the Swap UI. Learn more about showSwap.

Transaction Confirmation Screen​

You can use the wallet services provider to integrate prebuilt transaction confirmation screens into your application. Upon successful completion, you can retrieve the signature for the request. Learn more about transaction confirmation screens.