> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Recovery: Regain Access Without Losing Assets

> Restore wallet access after a lost passkey — identity verification replaces the credential while the wallet address, assets, and ownership stay intact.

Account recovery is for users who have lost access to their passkey — broken phone, deleted credential, hardware failure, or device theft. Recovery lets them prove their identity through an alternative path and register a new passkey in place of the lost one. Crucially, recovery never creates a new wallet, never moves assets, and never changes the wallet address. The Soroban smart contract that holds the user's assets is untouched; only the credential binding inside it is updated.

## The Core Guarantee

Before and after recovery, the wallet is identical in every way except the bound passkey:

```text theme={null}
Before recovery:
  Wallet:     CDXXXXXXXXXX...
  Assets:     500 USDC, 250 XLM
  Policies:   500 USDC/day spending limit
  Ownership:  User A
  Credential: Passkey A (lost phone) ← inaccessible

After recovery:
  Wallet:     CDXXXXXXXXXX...   ← same
  Assets:     500 USDC, 250 XLM ← same
  Policies:   500 USDC/day limit ← same
  Ownership:  User A             ← same
  Credential: Passkey B (new phone) ← updated
```

The user picks up exactly where they left off. No migration, no asset transfer, no new address to communicate to counterparties.

## Recovery vs Credential Rotation

Understanding when to use each operation is important:

|                             | Account Recovery               | Credential Rotation          |
| --------------------------- | ------------------------------ | ---------------------------- |
| **Use when**                | Passkey is lost / inaccessible | You still have your passkey  |
| **Authorization source**    | Identity verification          | Current passkey signature    |
| **Wallet address changes?** | No                             | No                           |
| **Assets move?**            | No                             | No                           |
| **Ownership changes?**      | No                             | No                           |
| **Seed phrase required?**   | No                             | No                           |
| **Who initiates?**          | User (from login screen)       | User (from account settings) |

<Note>
  If the user still has access to their current passkey, [credential rotation](/smart-wallet/credential-rotation) is the right choice. Recovery is only necessary when that passkey is truly gone.
</Note>

## The Recovery Flow

<Steps>
  <Step title="Request Recovery">
    The user navigates to the recovery path in your application — typically accessible from the login screen when they cannot authenticate normally. They identify their account (by email, username, or wallet address) and initiate the recovery request.

    ```text theme={null}
    User → "I can't sign in"
      ↓
    Recovery flow initiated
      ↓
    Account identified
    ```
  </Step>

  <Step title="Identity Verification">
    Because the user cannot prove ownership with their passkey (it's lost), they verify their identity through an alternative mechanism. This step is security-critical: it is the gate that prevents anyone from recovering someone else's wallet.

    ```text theme={null}
    Identity verification required
      ↓
    Verification method (email OTP, SMS, OAuth, etc.)
      ↓
    Verified ✅ or Rejected ❌
    ```

    <Warning>
      Recovery is one of the highest-privilege wallet operations. Identity verification must be robust — successful recovery grants full control of the wallet. Treat any unexpected recovery notification as a potential account takeover attempt and investigate immediately.
    </Warning>
  </Step>

  <Step title="Recovery Authorization">
    After identity verification succeeds, the recovery system generates a cryptographic recovery authorization. This authorization acts as a one-time proof that the recovery system has verified the user's identity and approves the credential replacement. It has a limited validity window.

    ```text theme={null}
    Identity verified
      ↓
    Recovery authorization generated
      ↓
    Authorization: time-limited, wallet-specific, single-use
    ```
  </Step>

  <Step title="New Passkey Created">
    The user creates a new passkey on their current device. This produces a new public key and credential ID. As with credential rotation, a proof of possession is generated to prove the new passkey actually controls its claimed private key.

    ```text theme={null}
    New device / new authenticator
      ↓
    WebAuthn credential created
      ↓
    Challenge signed → Proof of possession verified ✅
    ```
  </Step>

  <Step title="Recovery Executed">
    The wallet contract receives the recovery authorization (from the identity verification step), the new credential's public key, and the proof of possession. It validates all three before executing the `recover_account()` operation.

    ```text theme={null}
    Wallet verifies:
    ─────────────────
    ① Recovery authorization — valid, unexpired, issued for this wallet?
    ② Recovery signature     — cryptographically valid?
    ③ New credential proof   — new passkey can sign correctly?
    ④ Expiration window      — within valid ledger range?
    ─────────────────
    All pass → execute recover_account()
    ```

    If any check fails, recovery is rejected and the wallet state is unchanged.
  </Step>

  <Step title="Access Restored">
    With `recover_account()` executed, the old credential is removed from the wallet's state and the new passkey is bound in its place. The user can immediately authenticate with their new passkey and resume normal wallet use.

    ```typescript theme={null}
    // User now authenticates normally with new passkey
    const session = await socketfi.authenticate();
    // session.userProfile.id is the same user — wallet is unchanged
    ```
  </Step>
</Steps>

## What Changes and What Does Not

| Wallet Property     | Before Recovery       | After Recovery          |
| ------------------- | --------------------- | ----------------------- |
| Wallet address      | `CDXXXXXXXXXX...`     | `CDXXXXXXXXXX...` ✅     |
| Asset balances      | 500 USDC              | 500 USDC ✅              |
| Applied policies    | Spending limit active | Spending limit active ✅ |
| Transaction history | N transactions        | N transactions ✅        |
| Ownership           | User A                | User A ✅                |
| Bound credential    | Passkey A (lost)      | Passkey B (new) 🔄      |

## Recovery Failure Scenarios

Recovery fails securely — a failed attempt leaves the wallet state unchanged:

<AccordionGroup>
  <Accordion title="Identity verification failed">
    The user could not complete the verification step (wrong OTP, failed OAuth, etc.). Recovery is rejected. The user may retry from the beginning. Repeated failures should trigger additional monitoring.
  </Accordion>

  <Accordion title="Invalid recovery authorization">
    The recovery authorization produced by the verification system did not pass the wallet contract's cryptographic check. This should not occur in normal operation; investigate if it does.
  </Accordion>

  <Accordion title="Proof of possession failed">
    The new passkey failed to sign the challenge correctly. The user should retry credential creation on their new device.
  </Accordion>

  <Accordion title="Expired recovery request">
    The recovery authorization window passed before the user completed the flow. The user must restart recovery from the identity verification step.
  </Accordion>
</AccordionGroup>

## Application Integration

Your application is responsible for surfacing the recovery entry point and providing status feedback. The recovery logic itself is handled by SocketFi infrastructure.

```typescript theme={null}
// After recovery, the user authenticates normally with their new passkey.
// The SDK recovery UI guides users through identity verification and new
// passkey registration — your application surfaces the entry point and
// handles the post-recovery state.

async function onRecoveryComplete() {
  // The user has completed the recovery flow and registered a new passkey.
  // Authenticate to obtain a fresh session — the wallet address is unchanged.
  const session = await socketfi.authenticate();

  // session.userProfile.id is the same user; their wallet is unchanged.
  // Update your UI state and redirect to the authenticated experience.
  return session;
}
```

<Tip>
  Always send the user a notification (email, push) when a recovery event completes on their account. If the recovery was legitimate, they expect this. If it was not, this notification is their first signal of an account takeover.
</Tip>

## Security Considerations

Recovery is the highest-privilege operation in the wallet lifecycle. The security of your recovery flow determines how resistant your wallets are to social engineering and account takeover.

* **Identity verification must be strong.** Weak verification (e.g., email alone) may be acceptable for low-value applications but is insufficient for high-value wallets.
* **Recovery authorizations are single-use and time-limited.** A recovery authorization that is not consumed within its validity window is automatically rejected.
* **Monitor for unusual recovery patterns.** Multiple recovery requests for the same wallet in a short window, or recovery requests from unusual geographic locations, are worth investigating.
* **Communicate the ownership guarantee to users.** Users who understand that recovery does not change ownership or move assets are less likely to be manipulated by social engineering that claims otherwise.