Back up a wallet

​

Portal-Managed Backups

1. 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.
2. The custodian backup share is encrypted and stored by Portal, with the encryption key stored in our KMS infrastructure.

​

Backup Methods

​

Passkey + Enclave

​

Implementation Requirements

1. Initialize the Portal class with a passkey object.
2. 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

• 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

1. Configure DNS - Point your passkey subdomain (e.g., passkeys.yourapp.com) to Portal’s infrastructure
2. Provision a TLS certificate - Create a certificate for your subdomain that Portal will store in our secure enclave
3. Configure CORS - Allowlist your application origins

Configuration

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

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

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

​

Implementation Requirements

1. Create a UI for password input.
2. Enforce password requirements. Customer can choose between password, PIN code, passcode, or any other text-based input.
3. If the user forgets their password, there are no additional recovery options.

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

​

Implementation Requirements

1. Set up Google Drive in a Google Cloud project and create an OAuth client ID of type Web application. Google sign-in runs in the Portal iframe, so Google checks the iframe’s origin, not your app’s: under Authorized JavaScript origins, add https://web.portalhq.io, or your custom subdomain, such as https://portal.yourdomain.com, if you set host.
2. Initialize the Portal class with a gdrive object containing the OAuth clientId and, optionally, a backupOption.
3. Once the SDK is ready, call backup with the Google Drive backup method argument from a user action, such as a button click.

import React, { FC, useEffect, 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',
  },
  gdrive: {
    clientId: 'YOUR_GOOGLE_OAUTH_CLIENT_ID',
    backupOption: 'appDataFolderWithFallback', // optional, defaults to 'gdriveFolder'
  },
})

const BackupButton: FC = () => {
  const [isReady, setIsReady] = useState(false)

  // Wallet calls must wait until the Portal iframe is ready.
  useEffect(() => portal.onReady(() => setIsReady(true)), [])

  const handleBackup = async () => {
    // Back up the wallet to Google Drive.
    await portal.backupWallet(BackupMethods.gdrive)
  }

  return (
    <button disabled={!isReady} onClick={handleBackup}>
      Back up to Google Drive
    </button>
  )
}

export default BackupButton

​

Choose where backups are stored

​

Share backups with your iOS and Android apps

• Create your web OAuth client in the same Google Cloud project as your iOS and Android OAuth clients, whichever backupOption you use.
• Match the location your other apps use. The Web SDK defaults to the user-visible folder, while the iOS and Android guides use the app data folder. With those settings, a backup made on iOS or Android is not found on the web. To share backups with those apps, set backupOption to 'appDataFolder', or to 'appDataFolderWithFallback' if your users already have web backups and won’t later recover with an option or app that reads only the user-visible folder (see Change the backup location for existing users). The React Native SDK only uses the user-visible folder, so keep 'gdriveFolder' to share backups with a React Native app.

​

Change the backup location for existing users

​

Google sign-in and sessions

• Pop-ups: Google sign-in opens in a pop-up window. The Portal iframe opens it, not your page, so browsers can block it even when the backup or recovery starts from a click. Chrome blocks it with its default settings; allowing pop-ups for your site, then reloading the page, lets it open. In 4.2.0 a blocked pop-up isn’t reported: backupWallet or recoverWallet fails only when the SDK’s request times out, after 90 seconds.
• Declined scopes: Google’s consent screen lets users untick individual scopes. If a scope the backupOption needs is not granted, the backup or recovery fails with [GoogleAuth] The user did not grant the required Google Drive scopes: followed by the scope URLs. Starting in 4.2.0 this applies to every backupOption, including the default.
• Sessions: an open page keeps using the Google access token it already has. After a page reload, Google sign-in can be reused for up to five minutes when the Portal iframe is on the same site as your app, for example with a custom subdomain. The SDK keeps that session in cookies on the iframe’s origin. With the default iframe host, which is on a different site from your app, browsers may not keep these cookies, so users may be asked to choose their Google account again after a reload.
• Scope changes: a saved session is reused only if it covers the scopes the current backupOption needs, so after you change backupOption the user may be asked to sign in again. Users who signed in with a Web SDK earlier than 4.2.0 may also be asked to choose their Google account again after you upgrade.

​

Drive errors

​

Firebase Auth Backup

​

Implementation requirements

1. Integrate Firebase Authentication in your web app (for example with the Firebase JavaScript SDK).
2. 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.
3. Run backup with BackupMethods.firebase only after Firebase storage is configured and the user is signed in.

​

Configure Firebase storage

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',
  })
}

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

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

• Firebase Auth Backup option
• configureFirebaseStorage reference