Account Recovery: Regain Access Without Losing Assets

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:

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)

If the user still has access to their current passkey, credential rotation is the right choice. Recovery is only necessary when that passkey is truly gone.

The Recovery Flow

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.

User → "I can't sign in"
  ↓
Recovery flow initiated
  ↓
Account identified

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.

Identity verification required
  ↓
Verification method (email OTP, SMS, OAuth, etc.)
  ↓
Verified ✅ or Rejected ❌

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.

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.

Identity verified
  ↓
Recovery authorization generated
  ↓
Authorization: time-limited, wallet-specific, single-use

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.

New device / new authenticator
  ↓
WebAuthn credential created
  ↓
Challenge signed → Proof of possession verified ✅

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.

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.

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.

// User now authenticates normally with new passkey
const session = await socketfi.authenticate();
// session.userProfile.id is the same user — wallet is unchanged

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:

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.

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.

Proof of possession failed

The new passkey failed to sign the challenge correctly. The user should retry credential creation on their new device.

Expired recovery request

The recovery authorization window passed before the user completed the flow. The user must restart recovery from the identity verification step.

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.

// 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;
}

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.

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.

Get Started

Authentication

Embedded Wallets

Transactions

Smart Wallet

Security

Account Recovery: Regain Access Without Losing Assets

The Core Guarantee

Recovery vs Credential Rotation

The Recovery Flow

What Changes and What Does Not

Recovery Failure Scenarios

Application Integration

Security Considerations

​The Core Guarantee

​Recovery vs Credential Rotation

​The Recovery Flow

​What Changes and What Does Not

​Recovery Failure Scenarios

​Application Integration

​Security Considerations

The Core Guarantee

Recovery vs Credential Rotation

The Recovery Flow

What Changes and What Does Not

Recovery Failure Scenarios

Application Integration

Security Considerations