Passkey Recovery & Backup
What happens when you lose your passkey, and how to set up backup authentication for Chipi wallets.
The Problem
If a wallet is encrypted with a passkey and the user loses all their passkeys (e.g., lost phone, no backup), the wallet's private key cannot be decrypted. There is no master key or recovery phrase.
This is by design — self-custody means only the user controls their keys. But it also means backups are critical.
Prevention: Multiple Passkeys
The best defense is registering multiple passkeys across devices:
- Primary: Phone biometric (Face ID / fingerprint)
- Backup: Security key (YubiKey, USB/NFC)
- Optional: Laptop biometric, tablet, etc.
Each passkey is stored independently in passkeys.credentials[]. Any one of them can decrypt the wallet.
The Passkey Manager component lets users add and manage their passkeys.
If Passkey Is Lost
Scenario 1: Lost one device, have another
- - Sign in on the other device
- - Wallet works normally (any registered passkey can decrypt)
- - Remove the lost device's passkey via Passkey Manager
- - Register a new passkey for the replacement device
Scenario 2: Lost all passkeys, had PIN backup
- - If the wallet was originally created with PIN and the PIN is still stored in metadata, the user can sign with PIN
- - Then migrate to a new passkey
Scenario 3: Lost all passkeys, no PIN
- - The wallet is locked. The private key cannot be decrypted.
- - Funds are not lost (they're on-chain) but the user cannot sign transactions.
- - No recovery mechanism exists in the current SDK.
Best Practices
- Always register a backup passkey: Prompt users to add a security key after wallet creation
- Show passkey count: Display how many passkeys are registered. Warn if only 1.
- Don't delete the last passkey: The Passkey Manager prevents deleting the last PRF-enabled passkey
- Consider hybrid auth: For high-value wallets, keep both PIN and passkey active
- Educate users: Make it clear that losing all auth methods means losing wallet access