Password-based recovery

This guide explains how to set up passwords for user-managed recovery of embedded wallets.

Start with a walkthrough of the user experience of password-based recovery, and continue to concrete configuration details below.

User experience

Setting a password for user-managed recovery

Setup

When a user is prompted to set a password for their recovery share, the Privy modal will open in your app and guide the user through setting a secure password for their wallet.

The modal will require that the user confirm their password and will stress the importance of not losing the password, as loss of the password may lead to loss of access to the wallet.

Recovery

Once a user has set a password, when they attempt to use the wallet on a new device or browser, Privy will automatically prompt the user to input their password to recover the wallet.

Once the user successfully inputs their password, they can use the wallet on that device, and will not be prompted for the password on that device again.

Integration

Configuration

There is nothing you need to do to configure passwords as an option for user-managed recovery. Passwords are always an option for user-managed recovery flows.

Prompting users to set a password

Your app can either prompt users to set a password when they first create their wallet, or at a later point in time.

When a user is prompted to set a password, the Privy modal will open and prompt the user to set a secure password for their wallet. The modal will require that the user confirm their password and will stress the importance of not losing the password, as loss of the password may lead to loss of access to the wallet.

Requiring a password on wallet creation

To require that users set a password when they first create their wallet, visit the Embedded wallets page of the Privy Dashboard and navigate to the Recovery methods tab. Toggle the Require recovery method on wallet creation option on.

When this setting is on, users will automatically be prompted to set up user-managed recovery when they create their wallet. Note that:

• When setting up user-managed recovery, users can choose any of the recovery methods you have enabled in the Dashboard. This will always include passwords.
• If the user does not successfully set a password (or any other enabled user-managed recovery factor) when creating their wallet, a wallet will not be created for them.

Setting a password at a later point

To prompt users to set a password for their wallet after the wallet has already been created, use the setWalletPassword method from the usePrivy hook.

const {setWalletPassword} = usePrivy();

This method will open a modal where the user can set a password for their embedded wallet.

When invoked, setWalletPassword will return a Promise for the embedded wallet's updated Wallet object, that will resolve once the user has successfully set a password for their wallet.

The method will reject with an error if the user does not have an embedded wallet, or if the user has already set a password for their wallet. To determine if a user's embedded wallet is already secured by a password, check if the embedded wallet's entry in the user.linkedAccounts array has a recoveryMethod of 'user-passcode'.

const {user} = usePrivy();
const embeddedWallet = user.linkedAccounts.find(
  (account): account is WalletWithMetadata =>
    account.type === 'wallet' && account.walletClientType === 'privy',
);
const alreadyHasPassword = embeddedWallet.recoveryMethod === 'user-passcode';

As an example, you might add setWalletPassword as an event handler for a set password button in your app:

import {usePrivy} from '@privy-io/react-auth';

// This example assumes you have already checked that Privy is `ready` and the user is `authenticated`
function AddPasswordButton() {
  const {user, setWalletPassword} = usePrivy();
  // This is taken from the code snippet above
  const embeddedWallet = user.linkedAccounts.find(
    (account): account is WalletWithMetadata =>
      account.type === 'wallet' && account.walletClientType === 'privy',
  );
  const alreadyHasPassword = embeddedWallet.recoveryMethod === 'user-passcode';

  return (
    <button
      // Only users who have an embedded wallet and have not already set a password can click
      disabled={!embeddedWallet || !alreadyHasPassword}
      onClick={setWalletPassword}
    >
      Add a password to your wallet
    </button>
  );
}

INFO

Once a password has been set for a wallet, it is not currently possible to reset the password. We are actively building support for this flow.