Skip to main content

​
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”):
  1. 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, 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.
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

Allow customers to create a native passkey on their device that is used to authenticate into a secure enclave that holds the encryption key for the user. Customer’s passkeys are backed up to the native cloud storage for their device.

​
Implementation Requirements

  1. Install react-native-passkeys and @portal-hq/passkey-storage
  2. Initialize passkey storage as a backup option in the Portal Config Object.
  3. Configuring the relying party

​
Relying party

A relying party is a trusted domain that is tied to the public key credentials of your users for their passkey . We offer the option to use portalhq.io as your relying party domain. It requires you to add portalhq.io as an Associated Domain in your iOS application and share your team id + application bundle id. If you already have your domain as a webcredential for your application then you can simply pass in your domain as the relying party and everything should work.

​
Use Portal as your relying party

  1. Add portalhq.io as a web credential domain in your app.
  2. Share your app bundle id and team id with the Portal Team.

​
Use your own relying party

Ensure you have set up your associate domain correctly in your app and that you are serving an aasa file from your relying party domain. You will need to be sure you have the webcredential field set properly for your app in your aasa file.Resources from apple:

​
Relying Party Origins

Regardless of the relying party decision you make above, you will need to set the relying party origin to: 
android:apk-key-hash:<sha256_hash-of-apk-signing-cert>
Read more info here on how to get the SHA256 hash of the apk signing cert.

​
Password/PIN

Allow users to create a password/pin. Users can either remember the password or store it in a password storage manager.

​
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 user forgets password there are no additional recovery options.
import axios from 'axios'
import React, { FC } from 'react'
import { BackupMethods, usePortal } from '@portal-hq/core'
import { Button, View } from 'react-native'

const BackupButton: FC = () => {
  const [password, setPassword] = useState<string>('')
  const portal = usePortal()

  const handleBackup = async () => {
    // Get an encrypted client backup share from running backup.
    const cipherText = await portal.backupWallet(
      BackupMethods.Password,
      (status) => { console.log('Backup Status: ', status) },
      { passwordStorage: { password: password } },
    )

    try {
      // Send the backup share to your API and store it.
      await axios.post('{your_server}/users/[userId]/user-backup-shares', {
        data: { backupMethod: "PASSWORD", cipherText }
      })

      // ✅ Notify Portal that the user backup share was stored! 🙌
      await portal.api.storedClientBackupShare(true, "PASSWORD")
    } catch (error) {
      // ❌ Notify Portal that the user backup share was not stored.
      await portal.api.storedClientBackupShare(false, "PASSWORD")
    }
  }

  return (
    <View>
        <TextInput
          autoCapitalize="none"
          autoCorrect={false}
          onChangeText={setPassword}
          placeholder="Password/Pin"
          placeholderTextColor="#6B6E73"
          spellCheck={false}
          style={styles.input}
          value={password}
        />
      <Button onPress={handleBackup} title="Backup your wallet" />
    </View>
  )
}

export default BackupButton

​
iCloud

See the docs on how to set up iCloud.

​
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 SDK leverages Firebase ID tokens to securely store and retrieve encryption keys from the secure enclave. This is ideal if your 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

  1. Install @portal-hq/firebase-storage and integrate Firebase Authentication in your app (for example with @react-native-firebase/auth).
  2. Add a FirebaseStorage instance to the backup object on your Portal constructor options, with a getToken function that returns a valid Firebase ID token string or null when no user is signed in.

​
Configure Firebase storage

Register Firebase alongside your other backup adapters when you construct Portal. The SDK assigns your Portal API client to each storage adapter automatically, which FirebaseStorage needs for TBS requests. 
import Portal from '@portal-hq/core'
import { FirebaseStorage } from '@portal-hq/firebase-storage'
import { getAuth } from '@react-native-firebase/auth'

const firebaseStorage = new FirebaseStorage({
  getToken: async (options?: { forceRefresh?: boolean }) => {
    const user = getAuth().currentUser
    if (!user) {
      return null
    }
    return user.getIdToken(options?.forceRefresh ?? false)
  },
})

const portal = new Portal({
  apiKey: 'YOUR_PORTAL_CLIENT_API_KEY',
  backup: {
    gdrive: gDriveStorage,
    icloud: iCloudStorage,
    firebase: firebaseStorage,
  },
  // ...your remaining Portal options (chainId, gatewayConfig, keychain, etc.)
})
FirebaseStorage accepts an optional tbsHost if you need a non-default TBS URL; otherwise it uses the production host.
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.
Ensure the user is signed in to Firebase, then run backup. With Portal-Managed Backups (the default), Portal stores the encrypted client backup share for you.
import React, { FC } from 'react'
import { BackupMethods, usePortal } from '@portal-hq/core'
import { Button, View } from 'react-native'

const FirebaseBackupButton: FC = () => {
  const portal = usePortal()

  const handleBackup = async () => {
    await portal.backupWallet(
      BackupMethods.Firebase,
      (status) => {
        console.log('Backup status:', status)
      },
    )
  }

  return (
    <View>
      <Button onPress={handleBackup} title="Back up with Firebase" />
    </View>
  )
}

export default FirebaseBackupButton
Related Documentation