Recovering the wallet on a new device

Once a user has created an embedded wallet, when they attempt to use the wallet on a new device, the key material for their wallet must be transferred to that new device. This process is known as wallet recovery.

Privy supports two modes of recovery for the embedded wallet: automatic and user-managed.

Automatic recovery optimizes for the simplest experience when using the wallet on a new device, whereas user-managed recovery gives the user control over how the recovery share of the wallet is encrypted.

TIP

Read more about how recovery works in our security guide.

Automatic

In automatic recovery, Privy uses a server-side KMS to generate a secret used to secure the user's recovery share. The system is set up such that the secret can only be accessed by the user and is secured against any unauthorized modification or access; this is an architectural guarantee.

When the user needs to use their wallet on a new device, Privy returns the recovery share to that device only if the user is authenticated on that device and has a valid Privy token. The recovery share can then be decrypted using the secret. The resulting recovery share is combined with the auth share to provision the wallet on that device.

Automatic recovery occurs completely behind-the-scenes, and thus offers the lowest-friction experience for using the wallet on a new device. The user need only log in and their device will be automatically provisioned.

INFO

When creating a new embedded wallet, automatic is the default recovery setting, unless you modify it in the Dashboard.

User-managed

With user-managed recovery, the user can manage how their recovery share is encrypted. They can set a password to encrypt it directly, or have an auto-generated password saved directly to their cloud storage account (Google Drive or iCloud).

With user-managed recovery, a user will need to provide additional input when first using their wallet on a new device. They will need to input their password or sign in to their cloud account to provision their wallet on the new device. This also gives users the most control over how their recovery share is managed and when their wallet can be recovered on a new device.

Read more about the two recovery options for user-managed recovery below.

Password-based

In password-based recovery, the recovery share of the private key is secured by a password set by the user. Privy does not have access to the user's password, and therefore cannot decrypt the recovery share. This also means that password loss may mean the user cannot recover their wallet.

When a user attempts to use their wallet on a new device, Privy prompts the user to input their password on that device to decrypt the recovery share. Once the user correctly inputs their password, the wallet can be provisioned on the new device.

See the password recovery guide to see the user experience of password-based recovery and to learn how to prompt users to set it up.

INFO

When prompting users to set up user-managed recovery, passwords will always be a recovery option they can choose.

Cloud-based

In cloud-based recovery, the recovery share is secured by a secret generated on the user's device and backed up to the user's cloud account (e.g. Google Drive or iCloud). Privy does not have access to the recovery secret stored in the user's cloud storage, and therefore cannot decrypt the recovery share unilaterally.

When a user attempts to use their wallet on a new device, Privy will prompt the user to sign in to their cloud account to retrieve the recovery secret needed to decrypt the recovery share. Once they successfully sign-in, Privy combines the decrypted recovery share with the user's auth share to provision the wallet on that device. If a user loses access to their cloud account, they may be unable to recover their wallet.

See the cloud recovery guide to see the user experience of cloud-based recovery and to learn how to prompt users to set it up.