Skip to main content

Usage of Single Factor Auth JS 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.

Functionality Overview​

Natively, the instance of Web3Auth (called web3auth in our examples) has the following methods/getters:

NameDescription
connectUse this method to login a user to Web3Auth SFA JS SDK.
providerReturns the native provider that can be used to make different blockchain transactions.
sessionIdReturns the sessionId of the user as a string.
authenticateUserReturns a promise of the UserAuthInfo object containing the idToken of the user.
addChainAdd chain configuration to the web3auth instance.
switchChainSwitches the chainId to one of the added chainIds.
getUserInfoReturns the user information.
logoutLog out the user from the web3auth instance.

Logging in your User​

To log in a user using the Web3Auth SFA JS SDK, call the connect method. This method returns an IProvider instance upon successful authentication which can then be used to interact with various blockchain networks. For more details, refer to the provider documentation.

tip

Please refer to the Authentication section for more details on the setting up your verifier and other authentication parameters.

LoginParams​

The method accepts LoginParams as an input.

ParameterDescription
verifierName of the verifier. It's a mandatory parameter as a string.
verifierIdVerifier ID's value, sub or email value present in the idToken. It's a mandatory parameter as a string.
idTokenA newly created JWT Token that has not already been sent to Web3Auth or a Duplicate Token error will be thrown. It's a mandatory parameter as a string.
subVerifierInfoArray?Sub verifier info. It's an optional parameter as a TorusSubVerifierInfo[].
serverTimeOffset?Server time offset. It's an optional parameter as a number.

TorusSubVerifierInfo​

NameDescription
verifierName of the verifier. It's a string mandatory parameter.
idTokenA newly created JWT Token that has not already been sent to Web3Auth or a Duplicate Token error will be thrown. It's a string mandatory parameter.

Usage​

await web3auth.connect({
  // Get the verifier name from the Web3Auth Dashboard
  verifier: "YOUR_VERIFIER_NAME",
  // Pass the JWT token verification value selected for verifier.
  verifierId: "YOUR_VERIFIER_ID",
  // Pass your JWT token
  idToken: "YOUR_JWT_TOKEN",
});

Get a native provider​

The method returns the provider instance that can be used to interact with different blockchain networks. Please note, if there's no active session, the method will return null.

Please refer to the provider documentation for more details.

Usage​

const provider = web3auth.provider;
// Use the provider to interact with the blockchain

Get sessionId​

The method returns the session id for the current active session as the string.

Usage​

const sessionId = web3auth.sessionId;

Authenticate the user​

The method authenticates the connected user, and returns user auth info containing the Web3Auth JWT token. You can use the idToken for backend verification.

Usage​

const userAuthInfo = await web3auth.authenticateUser();

Response​

export type UserAuthInfo = {
  idToken: string;
};

Add a new chain​

To add a new chain to your Web3Auth provider instance you can use the addChain method.

Parameters​

The method accepts a CustomChainConfig object as an input.

NameDescription
chainNamespaceNamespace of the chain. It ChainNamespaceType type.
chainIdThe chain id of the network in Hex format.
rpcTargetRPC target URL for the chain. The RPC url is used to interact with the blockchain network.
wsTarget?Web socket target URL for the chain.
displayName?Display Name for the chain.
blockExplorerUrl?Blockchain explorer URL for the network.
ticker?Network's native currency ticker (e.g: ETH for Ethereum)
tickerName?Network's native currency name (e.g: Ethereum).
decimals?Network's native currency decimal precision (e.g: 18 for Ethereum). Default value is 18.
logo?Logo for the token.
isTestnet?Whether the network is testnet or not.

Switch the chain​

To switch the chain for the provider instance you need to call the switchChain method. Please make sure, you have first added the chain using the addChain method.

Parameters​

NameDescription
chainIdThe hex chain ID of the blockchain network you want to switch to

Usage​

// Switches the chain to the Polygon network
await web3auth.switchChain({ chainId: "0x89" });

Logging out the user​

To logout the user and clear the session, call the logout method. Please note, this method only clears the Web3Auth session, and doesn't clears the OAuth session.

Usage​

await web3auth.logout();

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.

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