Back up a wallet

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, Password, Passkey, or Firebase Auth). 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.

Both the client backup share and the custodian backup share are necessary to recover a Portal wallet.

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.

Portal-Managed Backups (Default)
Self-Managed Backups

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.

Firebase Auth Backup

Allow customers to use their existing Firebase Authentication to authenticate into a secure enclave that holds the encryption key for the user. The Portal Web SDK uses Firebase ID tokens to store and retrieve encryption keys from Portal’s token backup service (TBS). This is ideal if your web app already uses Firebase Auth — no additional authentication method is required from your users. See the Firebase Auth Backup setup guide for prerequisites and Firebase project configuration.

Implementation requirements

Integrate Firebase Authentication in your web app (for example with the Firebase JavaScript SDK).
Call portal.configureFirebaseStorage with a getToken callback that returns a Firebase ID token for the signed-in user, or null when no user is signed in.
Run backup with BackupMethods.firebase only after Firebase storage is configured and the user is signed in.

Unlike React Native, the Web SDK does not use a separate @portal-hq/firebase-storage package. Firebase backup is built into @portal-hq/web via configureFirebaseStorage. Your app supplies Firebase Auth; the Portal iframe requests ID tokens from the parent page through a secure postMessage bridge.

Configure Firebase storage

Call configureFirebaseStorage before backupWallet or recoverWallet with BackupMethods.firebase. You typically do this immediately before the backup or recovery flow, or once after the user signs in to Firebase.

import Portal, { BackupMethods } from '@portal-hq/web'
import { getAuth } from 'firebase/auth'

const portal = new Portal({
  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
  rpcConfig: {
    'eip155:11155111': 'YOUR_RPC_URL',
  },
})

async function configureFirebaseForPortal() {
  const auth = getAuth()

  portal.configureFirebaseStorage({
    getToken: async (options?: { forceRefresh?: boolean }) => {
      const user = auth.currentUser
      if (!user) {
        return null
      }
      // Portal may call this again with forceRefresh after a 401 — forward it to getIdToken.
      return user.getIdToken(Boolean(options?.forceRefresh))
    },
    // Optional: override TBS host (defaults to backup.web.portalhq.io)
    tbsHost: 'backup.web.portalhq.io',
  })
}

The user must be signed in to Firebase before running backup or recovery. If there is no signed-in user, getToken should return null and the operation will fail.

The tab examples below assume a portal instance and configureFirebaseForPortal helper from the Configure Firebase storage section above.

Portal-Managed Backups
Self-Managed Backups

Ensure the user is signed in to Firebase, configure storage, then run backup. With Portal-Managed Backups (the default), Portal stores the encrypted client backup share for you.

import React from 'react'
import { BackupMethods } from '@portal-hq/web'

const FirebaseBackupButton: React.FC = () => {
  const handleBackup = async () => {
    await configureFirebaseForPortal()

    const { cipherText, storageCallback } = await portal.backupWallet(
      BackupMethods.firebase,
      (status) => {
        console.log('Backup status:', status)
      },
    )

    await storageCallback()
    console.log('Backup cipherText:', cipherText)
  }

  return (
    <button onClick={handleBackup}>Back up with Firebase</button>
  )
}

export default FirebaseBackupButton

With self-managed storage, you persist the encrypted client backup share (cipherText) in your own backend, then tell Portal the write succeeded or failed. See Self-Managed Backups for the full model.

import axios from 'axios'
import React from 'react'
import { BackupMethods } from '@portal-hq/web'

const FirebaseSelfManagedBackupButton: React.FC = () => {
  const handleBackup = async () => {
    await configureFirebaseForPortal()

    const { cipherText, storageCallback } = await portal.backupWallet(
      BackupMethods.firebase,
      (status) => {
        console.log('Backup status:', status)
      },
    )

    try {
      await axios.post('{your_server}/users/[userId]/user-backup-share', {
        data: { backupMethod: 'FIREBASE', cipherText },
      })

      await portal.storedClientBackupShare(true, BackupMethods.firebase)
      await storageCallback()
    } catch (error) {
      await portal.storedClientBackupShare(false, BackupMethods.firebase)
    }
  }

  return (
    <button onClick={handleBackup}>Back up with Firebase</button>
  )
}

export default FirebaseSelfManagedBackupButton

Related documentation

Documentation Index

​Portal-Managed Backups

​Backup Methods

​Passkey + Enclave

​Implementation Requirements

​Custom Domain Passkeys

Setup Requirements

Configuration

Step 1: Create a Passkey

Step 2: Create a Backup

​Password/PIN

​Implementation Requirements

​Google Drive

​Firebase Auth Backup

​Implementation requirements

​Configure Firebase storage

Portal-Managed Backups

Backup Methods

Passkey + Enclave

Implementation Requirements

Custom Domain Passkeys

Password/PIN

Implementation Requirements

Google Drive

Firebase Auth Backup

Implementation requirements

Configure Firebase storage