LogoLogo
SupportGithubSign InGet Access
  • Introduction
  • GETTING STARTED
    • SDK Quick Start
    • API Quick Start
  • Guides
    • Web
      • Create a wallet
      • Send tokens
      • Sign a transaction
      • Simulate a transaction
      • Back up a wallet
      • Recover a wallet
      • Cross-device sessions
      • Manage wallet lifecycle states
      • Web authentication methods
      • Perform swaps
      • Add custom signature hooks
      • MPC progress callbacks
      • Portal API methods
      • Configure a custom subdomain
      • Eject a wallet
      • Using the EIP-1193 Provider
      • Legacy documentation
        • Back up a wallet
          • Backup Options
        • Recover a wallet
    • iOS
      • Create a wallet
      • Send tokens
      • Sign a transaction
      • Simulate a transaction
      • Back up a wallet
      • Recover a wallet
      • Cross-device sessions
      • Manage wallet lifecycle states
      • Connect with WalletConnect
      • Build a WebView
      • Perform swaps
      • Add custom signature hooks
      • MPC progress callbacks
      • Portal API methods
      • Manage ERC20 tokens
      • Eject a wallet
      • Legacy documentation
        • Back up a wallet
          • Backup Options
          • Passkey + Enclave Storage
        • Recover a wallet
      • Troubleshooting Tips
      • Feature Flags
    • Android
      • Create a wallet
      • Send tokens
      • Sign a transaction
      • Simulate a transaction
      • Back up a wallet
      • Recover a wallet
      • Cross-device sessions
      • Manage wallet lifecycle states
      • Connect with WalletConnect
      • Build a WebView
      • Perform swaps
      • Add custom signature hooks
      • MPC progress callbacks
      • Portal API methods
      • Eject a wallet
      • Legacy documentation
        • Back up a wallet
          • Backup Options
        • Recover a wallet
    • React Native
      • Create a wallet
      • Send tokens
      • Sign a transaction
      • Simulate a transaction
      • Back up a wallet
      • Recover a wallet
      • Cross-device sessions
      • Manage wallet lifecycle states
      • Connect with WalletConnect
      • Build a WebView
      • Perform swaps
      • Add custom signature hooks
      • MPC progress callbacks
      • Portal API methods
      • Eject a wallet
      • Legacy documentation
        • Back up a wallet
          • Backup Options
        • Recover a wallet
    • Enclave MPC API
      • Create a client
      • Create a wallet
      • Send tokens
      • Sign Ethereum transactions
      • Sign Solana transactions
      • Sign Tron transactions
      • Sign Stellar Transaction
      • Concurrent Transactions
      • Back up a wallet
      • Eject a wallet
  • Reference
    • iOS
      • createWallet
      • backupWallet
      • recoverWallet
      • ejectPrivateKeys
      • registerBackupMethod
      • setGDriveConfiguration
      • setPasskeyConfiguration
      • setPasskeyAuthenticationAnchor
      • setPassword
      • availableRecoveryMethods
      • doesWalletExist
      • isWalletBackedUp
      • isWalletOnDevice
      • isWalletRecoverable
      • getBalances
      • getAssets
      • getNftAssets
      • getTransactions
      • sendSol
      • evaluateTransaction
      • buildEip155Transaction
      • buildSolanaTransaction
      • getWalletCapabilities
    • Android
      • Reference Documentation
    • React Native
      • @portal-hq/core
      • Storage adapters
        • Cloud storage
          • @portal-hq/gdrive-storage
          • @portal-hq/icloud-storage
        • Mobile storage
          • @portal-hq/keychain
          • @portal-hq/mobile-key-values
    • Enclave MPC API
      • V1 endpoints
    • Client API
      • V3 endpoints
      • V1 endpoints
    • Custodian API
      • V3 endpoints
      • V1 endpoints
    • Swaps API
      • V3 endpoints
      • V1 endpoints
  • Resources
    • Flutter
      • iOS
      • Android
    • Error codes
      • Overview
      • Legacy Documentation
        • MPC errors
        • Network errors
        • General errors
        • Encryption errors
        • Portal Connect errors
    • Portal's MPC architecture
    • Authentication and API Keys
    • Self-Managed Backups
    • Alert Webhooks
    • Wallet lifecycle
    • Backup options
      • Password/PIN
      • GDrive
      • iCloud
      • Passkey + Enclave
    • WalletConnect metadata
    • Advanced security scanning
    • Account abstraction
    • Security firewall
    • Eject
    • Security
    • Blockchain support
    • Chain ID formatting
    • Testnet faucets
    • Going to Production
    • Rate Limits
    • Multi-backup migration guide
    • Multi-wallet migration guides
      • Migrating from Android SDK v3.x.x to v4.x.x
      • Migrating from iOS SDK v3.0.x to v3.2.x
  • Support
    • Changelog
      • Android
      • iOS
      • React Native
      • Web
      • Past Releases
        • 2024 Releases
        • 2023 Releases
    • Celo Hackathon Hub
    • Glossary
Powered by GitBook
On this page
  • Portal-Managed Backups
  • Backup Methods
  • Passkey + Enclave
  • Password/PIN
  • iCloud
  • Google Drive

Was this helpful?

Edit on GitHub
  1. Guides
  2. iOS

Back up a wallet

This guide will walk you through how to create a backup of a Portal client's wallet.

PreviousSimulate a transactionNextRecover a wallet

Last updated 3 months ago

Was this helpful?

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, or Passkey). 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 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. Initialize passkey storage as a backup option in the Portal Config Object.

  2. Configuring the relying party

Use Portal as your relying party

  1. Add portalhq.io as a web credential domain in your app.

  2. Share your app bundle id with the Portal Team.

Use your own domain as the relying party

Ensure you have set up your associate domain correctly in your app and that you are serving an aasa file from whatever your relying party domain is set to. 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

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.

  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.Passkey) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
  // Your API URL
  let yourApiUrl: String = "https://YOUR_API_URL.com"
      
  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.Passkey) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
      
  // Obtain your API's URL for storing the encrypted user backup share.
  guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
    throw URLError(.badURL)
  }

  // Store the encrypted user backup share on your API.
  let requests = PortalRequests()
  try await requests.post(
    url,
    andPayload: [
      "backupMethod": withMethod.rawValue,
      "encryptedClientBackupShare": encryptedClientBackupShare,
    ]
  )

  // Call the storageCallback to notify Portal you stored the user backup share successfully.
  try await storageCallback()
  
  // ✅ The user has now backed up with their passkey successfully

Password/PIN

Allow customers to create a password/pin. Customers 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.

  // Set the user's password.
  try portal.setPassword("THE-USER-PASSWORD")
  
  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.Password) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
  // Your API URL
  let yourApiUrl: String = "https://YOUR_API_URL.com"
    
  // Set the user's password.
  try portal.setPassword("THE-USER-PASSWORD")
      
  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.Password) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
      
  // Obtain your API's URL for storing the encrypted user backup share.
  guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
    throw URLError(.badURL)
  }

  // Store the encrypted user backup share on your API.
  let requests = PortalRequests()
  try await requests.post(
    url,
    andPayload: [
      "backupMethod": withMethod.rawValue,
      "encryptedClientBackupShare": encryptedClientBackupShare,
    ]
  )

  // Call the storageCallback to notify Portal you stored the user backup share successfully.
  try await storageCallback()
  
  // ✅ The user has now backed up with their password successfully

iCloud

See the docs on how to configure iCloud.

For the iCloud action handling:

  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.iCloud) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
  // Your API URL
  let yourApiUrl: String = "https://YOUR_API_URL.com"
    
  // Set the user's password.
  try portal.setPassword("THE-USER-PASSWORD")
      
  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.iCloud) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
      
  // Obtain your API's URL for storing the encrypted user backup share.
  guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
    throw URLError(.badURL)
  }

  // Store the encrypted user backup share on your API.
  let requests = PortalRequests()
  try await requests.post(
    url,
    andPayload: [
      "backupMethod": withMethod.rawValue,
      "encryptedClientBackupShare": encryptedClientBackupShare,
    ]
  )

  // Call the storageCallback to notify Portal you stored the user backup share successfully.
  try await storageCallback()
  
  // ✅ The user has now backed up with their iCloud successfully

Google Drive

See the docs on how to configure GDrive.

After initializing Portal, you will need to configure the following:

  // Set GDrive Configuration
  try portal.setGDriveConfiguration(
        clientId: "your-google-client-id",
        backupOption: .appDataFolder
  )
    
  // Set the GDrive presenting view
  try portal.setGDriveView(self)

setGDriveConfiguration function parameters:

  • clientId: The client ID for the Google Drive integration.

  • backupOption: An option from the GDriveBackupOption enum that specifies the backup storage type:

    • appDataFolder: Stores backups in the hidden, app-specific "App Data Folder" in Google Drive. This folder is not visible to the user.

    • appDataFolderWithFallback: Attempts to store backups and recover using the "App Data Folder". If recover fails, it automatically falls back to a user-visible Google Drive.

    • gdriveFolder(folderName: String): Stores backups in a user-visible folder in Google Drive with the specified folderName.

setGDriveView function parameters:

  • view: A UIViewController instance that will be used to present Google Drive UI components.

For the GoogleDrive action handling:

  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.GoogleDrive) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
// Your API URL
  let yourApiUrl: String = "https://YOUR_API_URL.com"
    
  // Set the user's password.
  try portal.setPassword("THE-USER-PASSWORD")
      
  // Run backup.
  let (
    encryptedClientBackupShare,
    storageCallback
  ) = try await portal.backupWallet(.GoogleDrive) { status in
    // (Optional) Create a progress indicator here in the progress callback.
  }
      
  // Obtain your API's URL for storing the encrypted user backup share.
  guard let url = URL(string: "\(yourApiUrl)/users/\(userId)/store-encrypted-user-backup-share") else {
    throw URLError(.badURL)
  }

  // Store the encrypted user backup share on your API.
  let requests = PortalRequests()
  try await requests.post(
    url,
    andPayload: [
      "backupMethod": withMethod.rawValue,
      "encryptedClientBackupShare": encryptedClientBackupShare,
    ]
  )

  // Call the storageCallback to notify Portal you stored the user backup share successfully.
  try await storageCallback()
  
  // ✅ The user has now backed up with their Google Drive successfully

App Data Folder vs. GDrive Files

  • App Data Folder: A hidden, app-specific storage area that is not visible to the user in their Google Drive interface. This is ideal for sensitive data or configurations that the user doesn't need to manage directly.

  • Google Drive Files: A visible folder in the user's Google Drive, accessible and manageable by the user. This is suitable for backups the user might want to view, share, or organize manually.

The App Data Folder feature is supported starting from SDK version 4.2.0. If you enable this feature, ensure that you do not use any SDK version older than 4.2.0, as it will result in the loss of App Data Folder backups.

Related Documentation

Self-Managed Backups
Configuring an associated domain
Supporting associated domains
Backup options
registerBackupMethod function reference
setGDriveConfiguration function reference
setPasskeyConfiguration function reference
setPasskeyAuthenticationAnchor function reference
setPassword function reference
isWalletBackedUp function reference