# Embedded wallet recovery methods

:::info
Recovery methods apply exclusively to [embedded wallets](/docs/products/embedded-wallet).
:::

## Recovery basics

Recovering an embedded wallet is needed when a user logs into a new device or when access to the embedded wallet is lost.

Openfort embedded wallets have two core recovery modes: automatic recovery and user-based recovery. At a high-level, this setting modulates how the embedded wallet's recovery share is encrypted and stored. You can switch methods at any time; existing wallets continue to work.

* **[Automatic recovery](#automatic-recovery)**: The recovery share is encrypted with a combination of project entropy and Openfort's entropy. When logging into a new device, users can immediately access their embedded wallet.
  <br />
  :::tip
  Refer to [Automatic recovery session](/docs/products/embedded-wallet/server/automatic-recovery-session) guide to learn how to set up your backend endpoint to create the encryption session needed for automatic recovery.
  :::

* **[Password recovery](#password-recovery):** The recovery share is encrypted by **user-provided entropy**. When logging into a new device, users must enter in their password to recover the embedded wallet on the new device. Once the embedded wallet has been recovered on a device, users do not need to enter their password on that device again.

* **[Passkey recovery](#passkey-recovery):** The recovery share is encrypted by a **hardware-backed credential** (WebAuthn). When logging into a new device, users must authenticate with their passkey (Face ID/Touch ID or device unlock) to recover the embedded wallet on the new device. Once the embedded wallet has been recovered on a device, users do not need to authenticate with their passkey on that device again.

## Choose your wallet recovery method

Use this guide to quickly compare the three recovery options and pick the one that best fits your product and platform constraints.

| Feature | Automatic recovery | Password recovery | Passkey recovery |
| --- | --- | --- | --- |
| **User friction** | None during normal use; silent recovery | User enters a password when recovering | System prompts to create/use a passkey; biometric-friendly |
| **Security factor** | App-managed recovery via server-issued encryption session | User-chosen secret (password) | Hardware-backed credential (WebAuthn/Passkey) |
| **Backend required** | Yes — one endpoint + server-only encryption share | No | No |
| **Device portability** | Seamless across devices (via your backend) | Works anywhere user knows password | Works across devices that sync passkeys (iCloud Keychain, Google Password Manager) |
| **Platform support** | Any | Any | iOS 16+/macOS 13+, Android 9+, modern browsers (Chrome/Safari/Edge with passkeys) |
| **Best for** | Highest conversion, invisible UX | Familiar flows, broad compatibility | Strong phishing-resistant UX with biometrics |

## How to choose

* If you need the lowest friction and can run a tiny backend, choose **Automatic recovery**.
* If you want a familiar, backend-free option, choose **Password recovery**.
* If your audience has modern devices and you want biometrics + phishing resistance, choose **Passkey recovery**.

## Automatic recovery

Automatic recovery restores a user's non-custodial wallet using a short-lived encryption session issued by your backend. This keeps day-to-day UX invisible while preserving ownership and security.

* **Pros**: Zero extra steps for users; seamless multi-device; minimal UX surface area.
* **Cons**: Requires a small backend endpoint; you must keep Shield keys secure.
* **Requirements**: A recovery endpoint that mints an encryption session (one API route).

:::warning
With automatic recovery, the root of trust is the user's auth token. Keep tokens secured (secure storage, short lifetimes), never expose your `SHIELD_ENCRYPTION_SHARE` to clients, and remember the encryption session is single-use and must be minted by your backend.
:::

:::note
Automatic recovery needs a one-route backend to mint a Shield encryption session used during recovery.
:::

## Password recovery

:::tip
Password and Passkey are user-based recovery methods (encrypted with user-provided entropy).
:::

Password recovery protects the user's wallet with a secret they know. On a new device, users enter their password to recover and continue.

* **Pros**: No backend needed; universally understood; works on any platform.
* **Cons**: Users must remember/manage a secret; risk of weak or forgotten passwords.
* **Requirements**: None beyond configuring the recovery method in your app.

## Passkey recovery

Passkey recovery uses platform passkeys (WebAuthn) for phishing-resistant, biometric-friendly recovery. Users authenticate with Face ID/Touch ID or device unlock. Keys are stored in the device's secure enclave and sync across devices via iCloud Keychain or Google Password Manager.

* **Pros**: Strong, hardware-backed security; excellent UX with biometrics; resistant to phishing.
* **Cons**: Requires modern OS/browser support; users may need a platform account to sync passkeys across devices.
* **Requirements**: Device/platforms that support passkeys; configure recovery method.

:::warning[Domain-bound credentials]
WebAuthn credentials are bound to a specific domain (the Relying Party). Credentials created for your domain (e.g., `example.com`) only work on that domain and its subdomains—they cannot be used on other domains.

**This means users cannot use the same passkey wallet on other applications.** If your product spans multiple domains, consider using [automatic recovery](#automatic-recovery) instead.
:::