Portal-Managed Backups
Portal lets you securely back up your users’ MPC wallets so they can recover their wallets even if their device is lost or damaged. By default, Portal encrypts and stores both backup shares (“Portal-Managed Backups”):
- The client backup share is encrypted on the user’s device, with the encryption key stored using their chosen backup method (Google Drive, iCloud, Password, or Passkey). The encrypted share is then stored by Portal.
- The custodian backup share is encrypted and stored by Portal, with the encryption key stored in our KMS infrastructure.
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. Backup Methods
You can choose one or more backup methods for storing the encryption key for the client backup share.
Passkey + Enclave
Your Portal clients can create a passkey to authenticate and manage the private encryption key within a secure enclave.
Implementation Requirements
- Initialize the
Portal class with a passkey object.
- Call backup with the Passkey backup method argument.
import React from 'react'
const BackupButton: React.FC = () => {
const handleBackup = async () => {
// Create a passkey backup of the wallet.
await portal.backupWallet(BackupMethods.passkey)
}
return (
<button onClick={handleBackup}>Back up your wallet</button>
)
}
export default BackupButton
import axios from 'axios'
import React from 'react'
const BackupButton: React.FC = () => {
const handleBackup = async () => {
// Get an encrypted user backup share from running backup.
const { cipherText } = await portal.backupWallet(BackupMethods.passkey)
try {
// Send the backup share to your API and store it.
// This is pseduo code, change it with your URL request to your backend and your expected body data.
await axios.post('{your_server}/users/[userId]/user-backup-share', {
data: { backupMethod: "PASSKEY", cipherText }
})
// ✅ Notify Portal that the user backup share was stored! 🙌
await portal.storedClientBackupShare(true, BackupMethods.passkey)
} catch (error) {
// ❌ Notify Portal that the user backup share was not stored.
await portal.storedClientBackupShare(false, BackupMethods.passkey)
}
}
return (
<button onClick={handleBackup}>Back up your wallet</button>
)
}
export default BackupButton
Custom Domain Passkeys
By default, Portal handles passkey operations through our hosted domain (portalhq.io). If you want passkeys to be associated with your own domain (e.g., yourapp.com), you can configure a custom relying party.
Benefits of using your own domain:
- Passkey prompts display your domain name instead of Portal’s
- Users see a consistent brand experience
- Passkeys are portable across your applications that share the same relying party
Setup Requirements
To use your own domain for passkeys, you’ll need to:
- Configure DNS - Point your passkey subdomain (e.g.,
passkeys.yourapp.com) to Portal’s infrastructure
- Provision a TLS certificate - Create a certificate for your subdomain that Portal will store in our secure enclave
- Configure CORS - Allowlist your application origins
Getting Started: Reach out to the Portal team for instructions on setting up a custom domain, including TLS certificate provisioning for our enclave.
Configuration
Once your custom domain is set up, configure your passkey options:
import Portal, { BackupMethods } from '@portal-hq/web'
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 portal = new Portal({
apiKey: 'YOUR_CLIENT_API_KEY',
rpcConfig: {
'eip155:11155111': 'YOUR_RPC_URL',
},
})
Step 1: Create a Passkey
Create a passkey for your user. This can be done separately from the backup flow:
import React from 'react'
const CreatePasskeyButton: React.FC = () => {
const handleCreatePasskey = async () => {
try {
// Register a passkey without storing an encryption key yet
await portal.registerPasskey(passkeyOptions)
console.log('Passkey created successfully')
} catch (error) {
console.error('Failed to create passkey:', error)
}
}
return (
<button onClick={handleCreatePasskey}>Create Passkey</button>
)
}
Step 2: Create a Backup
Once a passkey exists, you can create a backup and store the encryption key with it:
Portal-Managed Backups
Self-Managed Backups
import React from 'react'
const BackupButton: React.FC = () => {
const handleBackup = async () => {
try {
// Step 1: Generate backup share and encryption key
const { encryptionKey } = await portal.generateBackupShare(
(status) => console.log('Backup progress:', status)
)
// Step 2: Authenticate with passkey and store the encryption key
await portal.authenticatePasskeyAndWriteKey(encryptionKey, passkeyOptions)
// Portal stores the cipherText automatically
console.log('Backup completed successfully')
} catch (error) {
console.error('Backup failed:', error)
}
}
return (
<button onClick={handleBackup}>Back up with Passkey</button>
)
}
import axios from 'axios'
import React from 'react'
const BackupButton: React.FC = () => {
const handleBackup = async () => {
try {
// Step 1: Generate backup share and encryption key
const { cipherText, encryptionKey } = await portal.generateBackupShare(
(status) => console.log('Backup progress:', status)
)
// Step 2: Authenticate with passkey and store the encryption key
await portal.authenticatePasskeyAndWriteKey(encryptionKey, passkeyOptions)
// Step 3: Store the cipherText in your backend
// This is pseduo code, change it with your URL request to your backend and your expected body data.
await axios.post('{your_server}/users/[userId]/user-backup-share', {
data: { backupMethod: 'CUSTOM', cipherText } // Note this backup method is CUSTOM not PASSKEY (since its decoupled from mpc)
})
// Step 4: Signal to Portal that backup storage is complete
await portal.storedClientBackupShare(true, BackupMethods.custom)
console.log('Backup completed successfully')
} catch (error) {
// Signal failure to Portal
await portal.storedClientBackupShare(false, BackupMethods.custom)
console.error('Backup failed:', error)
}
}
return (
<button onClick={handleBackup}>Back up with Passkey</button>
)
}
Password/PIN
Your Portal clients can create a password/PIN. They can either remember the password or store it in a password storage manager.
Implementation Requirements
- Create a UI for password input.
- Enforce password requirements. Customer can choose between password, PIN code, passcode, or any other text-based input.
- If the user forgets their password, there are no additional recovery options.
Portal-Managed Backups
Self-Managed Backups
import React, { FC, useState } from 'react'
import Portal, { BackupMethods } from '@portal-hq/web'
const portal = new Portal({
apiKey: 'YOUR_CLIENT_API_KEY',
rpcConfig: {
'eip155:11155111': 'YOUR_RPC_URL',
},
})
const BackupButton: FC = () => {
const [password, setPassword] = useState<string>('')
const handleBackup = async () => {
// Create a password backup for the wallet.
await portal.backupWallet(BackupMethods.password, undefined, { passwordStorage: { password } })
}
return (
<div>
<input
onChange={(e) => setPassword(e.target.value)}
placeholder="Password/Pin"
type="password"
value={password}
/>
<button onClick={handleBackup}>Back up your wallet</button>
</div>
)
}
export default BackupButton
import axios from 'axios'
import React, { FC, useState } from 'react'
import Portal, { BackupMethods } from '@portal-hq/web'
const portal = new Portal({
apiKey: 'YOUR_CLIENT_API_KEY',
rpcConfig: {
'eip155:11155111': 'YOUR_RPC_URL',
},
})
const BackupButton: FC = () => {
const [password, setPassword] = useState<string>('')
const handleBackup = async () => {
// Get an encrypted client backup share from running backup.
const { cipherText } = await portal.backupWallet(BackupMethods.password, undefined, { passwordStorage: { password } })
try {
// Send the backup share to your API and store it.
// This is pseduo code, change it with your URL request to your backend and your expected body data.
await axios.post('{your_server}/users/[userId]/user-backup-share', {
data: { backupMethod: "PASSWORD", cipherText }
})
// ✅ Notify Portal that the user backup share was stored! 🙌
await portal.storedClientBackupShare(true, BackupMethods.password)
} catch (error) {
// ❌ Notify Portal that the user backup share was not stored.
await portal.storedClientBackupShare(false, BackupMethods.password)
}
}
return (
<div>
<input
onChange={(e) => setPassword(e.target.value)}
placeholder="Password/Pin"
type="password"
value={password}
/>
<button onClick={handleBackup}>Back up your wallet</button>
</div>
)
}
export default BackupButton
Google Drive
See the docs on how to set up Google Drive.
