Portal-Managed Recovery (default)
When using Portal-Managed Backups, you can simply call the portal.recoverWallet() function passing an empty string for the cipherText parameter. Portal will then fetch the cipherText from our backend and complete the recovery process.
// With Password backup
await portal.recoverWallet('', BackupMethods.password, {
passwordStorage: {
password: "${USER_PROVIDED_PASSWORD}"
}
})
// With GDrive backup
await portal.recoverWallet('', BackupMethods.gdrive)
// With PasskeyBackups
await portal.recoverWallet('', BackupMethods.passkey)
WARNING: To recover a wallet with the Portal SDK, your device must be configured to use passcode authentication. Please note that if you disable your passcode authentication after executing the recover function, you will need to run the recover function again.
Self-Managed Recovery
By default, Portal manages storing both the encrypted client backup share and the custodian backup share for you. If you prefer to store and manage the backup shares in your own infrastructure instead of using Portal-Managed Backups, see our Self-Managed Backups guide.
Before recovering, you will need to retrieve the encrypted client backup share from your API. You will then provide the encrypted client backup share to portal.recoverWallet. Here’s an example of how that might look in your code:
// Fetch the encrypted client backup share from your API.
const cipherText = await axios.get('/users/[userId]/user-backup-share?backupMethod=GDRIVE')
// Recover replaces your current signing shares (if there are any) with new ones.
await portal.recoverWallet(cipherText, BackupMethods.gdrive)
WARNING: To recover a wallet with the Portal SDK, your device must be configured to use passcode authentication. Please note that if you disable your passcode authentication after executing the recover function, you will need to run the recover function again.
Passkey Recovery
To recover a wallet that was backed up with a passkey:
Portal-Managed Recovery
Self-Managed Recovery
import React from 'react'
const RecoveryButton: React.FC = () => {
const handleRecovery = async () => {
// Portal fetches the cipherText automatically
const address = await portal.recoverWallet(
'',
BackupMethods.passkey,
{},
(status) => console.log('Recovery progress:', status)
)
console.log('Recovered wallet address:', address)
}
return (
<button onClick={handleRecovery}>Recover wallet</button>
)
}
export default RecoveryButton
import axios from 'axios'
import React from 'react'
const RecoveryButton: React.FC = () => {
const handleRecovery = async () => {
// Fetch the cipherText from your backend
const response = await axios.get('{your_server}/users/[userId]/user-backup-share')
const cipherText = response.data.cipherText
const address = await portal.recoverWallet(
cipherText,
BackupMethods.passkey,
{},
(status) => console.log('Recovery progress:', status)
)
console.log('Recovered wallet address:', address)
}
return (
<button onClick={handleRecovery}>Recover wallet</button>
)
}
export default RecoveryButton
Custom Domain Passkeys Recovery
If you configured a custom domain for passkeys (see Custom Domain Passkeys), use the following recovery flow:
Portal-Managed Recovery
Self-Managed Recovery
import React from 'react'
import { PasskeyOptions } from '@portal-hq/web/types'
const passkeyOptions: PasskeyOptions = {
customDomain: 'https://passkeys.yourapp.com', // Your configured subdomain. This will be the same across all environments, even local.
relyingPartyId: 'yourapp.com', // Your root domain. For local dev set this to `localhost`
relyingPartyName: 'Your App Name', // Displayed in passkey prompts
usePopup: false, // Direct WebAuthn calls
}
const RecoveryButton: React.FC = () => {
const handleRecovery = async () => {
try {
// Step 1: Authenticate with passkey to get encryption key
const encryptionKey = await portal.authenticatePasskeyAndRetrieveKey(passkeyOptions)
// Step 2: Recover wallet - Portal fetches cipherText automatically
const address = await portal.recoverWallet(
'',
BackupMethods.custom,
{ customStorage: { encryptionKey } },
(status) => console.log('Recovery progress:', status)
)
console.log('Recovered wallet address:', address)
} catch (error) {
console.error('Recovery failed:', error)
}
}
return (
<button onClick={handleRecovery}>Recover with Passkey</button>
)
}
import axios from 'axios'
import React from 'react'
import { PasskeyOptions } from '@portal-hq/web/types'
const passkeyOptions: PasskeyOptions = {
customDomain: 'https://passkeys.yourapp.com', // Your configured subdomain. This will be the same across all environments, even local.
relyingPartyId: 'yourapp.com', // Your root domain. For local dev set this to `localhost`
relyingPartyName: 'Your App Name', // Displayed in passkey prompts
usePopup: false, // Direct WebAuthn calls
}
const RecoveryButton: React.FC = () => {
const handleRecovery = async () => {
try {
// Step 1: Retrieve cipherText from your backend
const response = await axios.get('{your_server}/users/[userId]/user-backup-share')
const cipherText = response.data.cipherText
if (!cipherText) {
throw new Error('No backup found')
}
// Step 2: Authenticate with passkey to get encryption key
const encryptionKey = await portal.authenticatePasskeyAndRetrieveKey(passkeyOptions)
// Step 3: Recover wallet with the encryption key
const address = await portal.recoverWallet(
cipherText,
BackupMethods.custom,
{ customStorage: { encryptionKey } },
(status) => console.log('Recovery progress:', status)
)
console.log('Recovered wallet address:', address)
} catch (error) {
console.error('Recovery failed:', error)
}
}
return (
<button onClick={handleRecovery}>Recover with Passkey</button>
)
}
Important: You must have called portal.storedClientBackupShare(true, BackupMethods.custom) after successfully storing the cipherText during backup. If this was not called, recovery will fail with the error “Cannot run recovery, backup was not completed successfully”.
Progress Callbacks
You can learn how to handle the progress callbacks for portal.recoverWallet here.
Next steps
Amazing! Your users can now have multiple backups and can easily recover their wallet. Next let’s dive into handling sessions across multiple devices for your users.
