Google Drive backup setup

Configure Google Drive as a backup option for embedded wallet recovery

To enable Google Drive backup for your users, you need to complete two configuration steps:

1. Enable in Dynamic dashboard

Navigate to your Dynamic Dashboard and enable Google Drive as a backup option in your embedded wallet settings.

2. Enable Google Drive API in Google Cloud Console

You must enable the Google Drive API in your Google Cloud project. If the API is not enabled, users will see an error like:

Google Drive API has not been used in project before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/drive.googleapis.com/overview then retry.

To enable the API:

1. Go to the Google Cloud Console
2. Select your project
3. Navigate to APIs & Services > Library
4. Search for “Google Drive API”
5. Click Enable

If you recently enabled the API, wait a few minutes for the changes to propagate before retrying.

Required OAuth scopes

When users authenticate with Google Drive, the following scopes are requested:

Scope	Purpose
https://www.googleapis.com/auth/drive.appdata	Allows storage in the app-specific hidden folder. This data is only accessible by your application and is not visible to the user in their Drive.
https://www.googleapis.com/auth/drive.file	Allows storage in the user’s personal Google Drive. This provides a user-accessible backup location.

Google presents these scopes on the consent screen as opt-in checkboxes that are unchecked by default — see the “Select what your-app can access” panel below. If the user clicks Continue without ticking both boxes (or only ticks one), the Google account will be linked but the Drive upload will fail.

Surface a clear instruction near the “Backup to Google Drive” CTA — for example: “On the Google consent screen, please check both Google Drive permissions so we can save your backup.” This is also why we recommend the pre-flight readiness check below: it lets you detect and recover from the partially-granted scope case before triggering the MPC reshare ceremony.

Dual storage locations

The User Share is stored in two locations for redundancy:

1. App Data folder - A hidden, application-specific storage area in Google Drive. Only your application can access this data, providing secure storage that users cannot accidentally delete.

2. Personal Google Drive - A user-visible backup in the user’s Drive. This ensures users have direct access to their backup if needed.

This dual storage approach ensures maximum reliability for wallet recovery while maintaining security.

Even though developers can obtain OAuth access tokens for users who authenticate with Google, this does not grant access to the user’s wallet. The key share stored in Google Drive cannot be used by the developer or backend to reconstruct the wallet, and it remains inaccessible without the user’s participation.

Key share encryption

For meaningful protection, we recommend setting a password for the key share during wallet creation or update. This is the security boundary that prevents anyone (including developers) from decrypting the backup.

If no password is provided, the key share is still stored in an encrypted format ensuring the key share cannot be used outside the project context.

Linking Google account

Users don’t need to sign in with Google to enable this feature. They can link their Google account at any point after wallet creation to enable Google Drive backup. See social linking for more details on how users can connect their Google account.

How key share backup works

The share that gets backed up to Google Drive depends on whether delegation is enabled for your project.

Google Drive only (2-of-3)

When a user backs up to Google Drive without delegation, a reshare operation creates new key shares:

• The client keeps Share B (stored at both Dynamic backend and locally)
• A new Share C is created and uploaded exclusively to Google Drive

This means Google Drive holds a different share than the client’s local/Dynamic share.

Delegation + Google Drive (2-of-3)

When delegation is enabled (either before or after Google Drive), the share distribution changes:

• The client’s Share B is backed up to both Dynamic and Google Drive (same share in both locations)
• A new Share C (the delegated share) is sent to the project’s webhook

In this scenario, Google Drive acts as a redundant backup of the client’s share rather than holding a unique share. This design ensures the delegated share remains exclusively on the webhook server, maintaining the security model where the project environment controls access to the delegated share.

Programmatic backup management

You can programmatically manage Google Drive backups using the useWalletBackup hook. This hook allows you to:

• Trigger backup flows programmatically
• Check backup status
• Manage backup configurations

See the useWalletBackup documentation for implementation details.

Pre-flight readiness check

Backup uploads to Google Drive can fail if the user’s linked Google account is missing one of the required OAuth scopes (for example, the user previously linked Google for sign-in only and never granted Drive access). Without a pre-flight check, the SDK would still kick off an MPC reshare ceremony before discovering the upload can’t succeed.

The useGoogleDriveBackupReadiness hook lets you detect — and recover from — these situations before triggering the ceremony. It pairs with useWalletBackup as a two-layer defense:

• Layer 1 — pre-flight readiness: call check() when the user opens the backup CTA. If status is 'needs-access', call requestAccess() to re-prompt the Google consent screen, then proceed with backupWallet(...).
• Layer 2 — post-flight recovery UI: for legacy users where the stored OAuth scopes weren’t recorded, pre-flight cannot tell whether the upload will succeed. Inspect lastBackupError from useWalletBackup during render — when the isInsufficientGoogleDriveScopesError type guard matches, show a “Re-grant Drive access” button that calls requestAccess() and retries backupWallet(...) on click.

See the useGoogleDriveBackupReadiness reference for a full code example.

Webhook event

When a user successfully backs up their key shares to Google Drive, Dynamic fires the wallet.keyShares.backedUpToExternal webhook event. You can use this to track backup status or trigger follow-up actions in your application. See webhook events for more details.