> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Back up a wallet

> This guide will walk you through how to create a backup of a Portal client's 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"):

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.

<Note>
  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](../../../resources/self-managed-backups) guide.
</Note>

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. Configure passkey storage with a relying party.
2. Set up your associated domain correctly in your app.

#### 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 associated 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.

#### 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 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.

<Tabs>
  <Tab title="Portal-Managed Backups (default)">
    ```dart theme={null}
    // Configure passkey storage.
    await portal.configurePasskeyStorage(
      relyingPartyId: 'portalhq.io',
      relyingPartyOrigins: ['https://portalhq.io'],
    );

    // Run backup.
    final response = await portal.backupWallet(
      method: PortalBackupMethod.passkey,
    );
    ```
  </Tab>

  <Tab title="Self-Managed Backups">
    ```dart theme={null}
    const method = PortalBackupMethod.passkey;

    await portal.configurePasskeyStorage(
      relyingPartyId: 'portalhq.io',
      relyingPartyOrigins: ['https://portalhq.io'],
    );

    // Run backup.
    final response = await portal.backupWallet(method: method);

    try {
      // Store the encrypted client backup share on your API.
      await yourApi.storeEncryptedClientBackupShare(
        userId: userId,
        backupMethod: 'passkey',
        cipherText: response.cipherText,
      );
    } catch (_) {
      // Storage step failed — release the pending callback so the user can retry.
      await response.discard();
      rethrow;
    }

    // Storage succeeded — mark the backup complete with Portal.
    await response.confirm();

    // ✅ The user has now backed up with passkey successfully
    ```
  </Tab>
</Tabs>

### 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.

<Tabs>
  <Tab title="Portal-Managed Backups">
    ```dart theme={null}
    // Run backup.
    final response = await portal.backupWallet(
      method: PortalBackupMethod.password,
      password: 'THE-USER-PASSWORD',
    );
    ```
  </Tab>

  <Tab title="Self-Managed Backups">
    ```dart theme={null}
    const method = PortalBackupMethod.password;

    // Run backup.
    final response = await portal.backupWallet(
      method: method,
      password: 'THE-USER-PASSWORD',
    );

    try {
      // Store the encrypted client backup share on your API.
      await yourApi.storeEncryptedClientBackupShare(
        userId: userId,
        backupMethod: 'password',
        cipherText: response.cipherText,
      );
    } catch (_) {
      // Storage step failed — release the pending callback so the user can retry.
      await response.discard();
      rethrow;
    }

    // Storage succeeded — mark the backup complete with Portal.
    await response.confirm();

    // ✅ The user has now backed up with password successfully
    ```
  </Tab>
</Tabs>

### 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](../../../resources/backup-options/firebase-byo-auth) for prerequisites and Firebase project configuration.

#### Configure Firebase storage

After initializing your Portal instance, call `configureFirebaseStorage` with a `getToken` callback that returns a fresh Firebase ID token:

```dart theme={null}
import 'package:firebase_auth/firebase_auth.dart';
import 'package:portal_flutter/portal_flutter.dart';

final portal = Portal();

// Configure Firebase as a backup method.
await portal.configureFirebaseStorage(
  getToken: () async {
    final user = FirebaseAuth.instance.currentUser;
    if (user == null) return null;
    return await user.getIdToken(true);
  },
);
```

<Warning>
  The user must be signed in to Firebase before performing any backup or recovery operations. If no Firebase user is signed in, the `getToken` callback returns `null` and the operation will fail.
</Warning>

<Tabs>
  <Tab title="Portal-Managed Backups (default)">
    ```dart theme={null}
    // Ensure user is signed in to Firebase, then run backup.
    final response = await portal.backupWallet(
      method: PortalBackupMethod.firebase,
    );
    ```
  </Tab>

  <Tab title="Self-Managed Backups">
    ```dart theme={null}
    const method = PortalBackupMethod.firebase;

    // Ensure user is signed in to Firebase, then run backup.
    final response = await portal.backupWallet(method: method);

    try {
      // Store the encrypted client backup share on your API.
      await yourApi.storeEncryptedClientBackupShare(
        userId: userId,
        backupMethod: 'firebase',
        cipherText: response.cipherText,
      );
    } catch (_) {
      // Storage step failed — release the pending callback so the user can retry.
      await response.discard();
      rethrow;
    }

    // Storage succeeded — mark the backup complete with Portal.
    await response.confirm();
    ```
  </Tab>
</Tabs>

### iCloud

See the docs on how to configure [iCloud](../../../resources/backup-options/icloud).

<Note>
  iCloud backup is only available on iOS devices. On Android, use Google Drive or Passkey backup instead.
</Note>

For the `iCloud` action handling:

<Tabs>
  <Tab title="Portal-Managed Backups">
    ```dart theme={null}
    // Configure iCloud storage (iOS only).
    await portal.configureICloudStorage();

    // Run backup.
    final response = await portal.backupWallet(
      method: PortalBackupMethod.iCloud,
    );
    ```
  </Tab>

  <Tab title="Self-Managed Backups">
    ```dart theme={null}
    const method = PortalBackupMethod.iCloud;

    await portal.configureICloudStorage();

    // Run backup.
    final response = await portal.backupWallet(method: method);

    try {
      // Store the encrypted client backup share on your API.
      await yourApi.storeEncryptedClientBackupShare(
        userId: userId,
        backupMethod: 'iCloud',
        cipherText: response.cipherText,
      );
    } catch (_) {
      // Storage step failed — release the pending callback so the user can retry.
      await response.discard();
      rethrow;
    }

    // Storage succeeded — mark the backup complete with Portal.
    await response.confirm();

    // ✅ The user has now backed up with iCloud successfully
    ```
  </Tab>
</Tabs>

### Google Drive

See the docs on how to configure [Google Drive](../../../resources/backup-options/gdrive).

#### Choosing a backup option

Pick where the encrypted backup is written via the `backupOption` parameter on `configureGoogleStorage`:

| `PortalGDriveBackupOption`  | Folder location                                                                                          | Visible to user?                | Recommended for                                        |
| --------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------ |
| `appDataFolder`             | Hidden, app-scoped Drive AppData folder.                                                                 | No                              | **New integrations** — invisible and tamper-resistant. |
| `appDataFolderWithFallback` | Writes to AppData; falls back to the SDK's built-in custom folder on read miss. `folderName` is ignored. | No (write); Yes (fallback read) | Migrating from a previous `customFolder` setup.        |
| `customFolder`              | User-visible folder named `folderName` (default `_PORTAL_MPC_DO_NOT_DELETE_`).                           | Yes                             | Apps already shipped with the legacy custom folder.    |

After initializing Portal, configure Google Drive storage:

```dart theme={null}
// Recommended for new integrations: hidden AppData folder.
await portal.configureGoogleStorage(
  clientId: 'your-google-client-id',
  backupOption: PortalGDriveBackupOption.appDataFolder,
);
```

For the `GoogleDrive` action handling:

<Tabs>
  <Tab title="Portal-Managed Backups">
    ```dart theme={null}
    // Run backup.
    final response = await portal.backupWallet(
      method: PortalBackupMethod.googleDrive,
    );
    ```
  </Tab>

  <Tab title="Self-Managed Backups">
    ```dart theme={null}
    const method = PortalBackupMethod.googleDrive;

    // Run backup.
    final response = await portal.backupWallet(method: method);

    try {
      // Store the encrypted client backup share on your API.
      await yourApi.storeEncryptedClientBackupShare(
        userId: userId,
        backupMethod: 'googleDrive',
        cipherText: response.cipherText,
      );
    } catch (_) {
      // Storage step failed — release the pending callback so the user can retry.
      await response.discard();
      rethrow;
    }

    // Storage succeeded — mark the backup complete with Portal.
    await response.confirm();

    // ✅ The user has now backed up with Google Drive successfully
    ```
  </Tab>
</Tabs>

#### Migrating existing users (AppData with fallback)

If your app previously shipped with the default `customFolder` configuration, switch to `appDataFolderWithFallback` so new backups land in AppData while existing users can still recover from the legacy custom folder:

```dart theme={null}
await portal.configureGoogleStorage(
  clientId: 'your-google-client-id',
  backupOption: PortalGDriveBackupOption.appDataFolderWithFallback,
);
```

#### Custom user-visible folder (default / legacy)

This is the behavior you get when `backupOption` is omitted — preserved for backward compatibility. You can still customize the folder name via `folderName`:

```dart theme={null}
await portal.configureGoogleStorage(
  clientId: 'your-google-client-id',
  folderName: 'MyAppBackups',
);
```

## Checking Backup Status

You can check if a wallet has been backed up:

```dart theme={null}
final isBackedUp = await portal.isWalletBackedUp();

if (isBackedUp) {
  print('Wallet is backed up');
} else {
  print('Wallet needs to be backed up');
}
```

## Platform Support Matrix

| Backup Method | Android | iOS |
| ------------- | ------- | --- |
| Password      | ✓       | ✓   |
| Passkey       | ✓       | ✓   |
| Google Drive  | ✓       | ✓   |
| iCloud        | -       | ✓   |
| Firebase Auth | ✓       | ✓   |

**Related Documentation**

* [Backup options](../../../resources/backup-options/gdrive)
* [Firebase Auth Backup option](../../../resources/backup-options/firebase-byo-auth)
* [backupWallet function reference](../reference/backupwallet)
* [configureFirebaseStorage function reference](../reference/configurefirebasestorage)
* [configureGoogleStorage function reference](../reference/configuregooglestorage)
* [configurePasskeyStorage function reference](../reference/configurepasskeystorage)
* [setPassword function reference](../reference/setpassword)
* [isWalletBackedUp function reference](../reference/iswalletbackedup)