Configuring cloud recovery of embedded wallets

Follow this guide to configure cloud-based recovery of embedded wallets in the Privy Dashboard.

Google Drive

To enable Google Drive recovery for your app, you must also enable Google as a social login method. To do so, follow the guidance here.

When enabling Google as a login method, we strongly recommend that you configure your own OAuth credentials, as these credentials cannot be changed once Google Drive recovery is enabled. We strongly recommend that you configure your own credentials before enabling Google Drive as a login method.

TIP

After creating your own Google OAuth credentials, you must enable the Google Drive API on your OAuth app to use Google Drive-based recovery.

After setting up Google as a login method and configure your own OAuth credentials, visit the Embedded wallets page of the Dashboard. In the Recovery tab, enable Google Drive as a user-managed recovery option.

FAQ

Do I need to bring my own Google OAuth credentials in order to enable recovery?

No, however once you’ve enabled recovery, you cannot update your credentials so consider setting your own before you enable it.

Does auth have to be enabled to enable to the recovery method?

Yes, in order to enable Google Drive recovery, you must enable Google as a login method in your Privy dashboard.

Should I implement recovery in my app or enable it in the Dashboard first?

You should enable Google Drive as a recovery method for your app before beginning implementation, so it will work properly while you integrate and test. There are no negative side effects if you enable Google Drive recovery in the dashboard but do not have it implemented.

iCloud

iCloud recovery uses CloudKit in order to store a recovery secret to iCloud (via a CloudKit database). This is a separate authentication mechanism from using Apple as a social login method, and does not share the same configuration. This discrepancy is invisible to the end user, who will log into their standard iCloud account to authorize recovery.

INFO

iCloud recovery is supported in both React and Expo (iOS). Other SDKs, as well as Expo (Android) are not supported.

INFO

iCloud recovery with Privy always uses the production CloudKit environment. This does not interfere with you using the development environment for non-Privy CloudKit testing, and does not stop you from testing Privy recovery in any of your application environments.

WARNING

Only a singular Allowed App URL Scheme (i.e. myapp://) is permitted when using iCloud recovery with Expo. If you need to support multiple URL schemes, such as for multiple environments, you will need to have distinct Privy app IDs.

1. Set up a CloudKit container

If you do not have a CloudKit container already setup, you will need to scaffold one (if you do, you can use your existing!). This can be done via Xcode (in the iCloud section of the Signing & Capabilities Target menu) or by connecting a CloudKit container to your app's bundle identifier (via the Apple Developer Portal). See Apple's documentation for detail.

2. Add the Privy wallet schema

To start, configure your CloudKit schema.

Privy stores user recovery secrets to a specific private CloudKit schema that must be imported. The schema (shown below) can be downloaded here, or copied into a local .ckdb file.

DEFINE SCHEMA

    RECORD TYPE PrivyWallets (
        "___createTime" TIMESTAMP,
        "___createdBy"  REFERENCE,
        "___etag"       STRING,
        "___modTime"    TIMESTAMP,
        "___modifiedBy" REFERENCE,
        "___recordID"   REFERENCE QUERYABLE,
        app_id          STRING,
        recovery_secret STRING,
        user_id         STRING,
        wallet_address  STRING
    );

This file can the be imported into CloudKit using the Import Schema link in the CloudKit dashboard sidebar.

Once imported, deploy the added schema to Production. You should only use this production CloudKit deployment going forward, including for your development or staging Privy app IDs.

3. Add tokens to CloudKit

Next, add tokens to your production CloudKit deployment to allow Privy's API to interface with it.

Due to platform implementation requirements, Expo and Web have distinct token types. If targeting both platforms, you will need to configure tokens for each.

WARNING

Ensure that you are adding tokens to your CloudKit production deployment.

Expo

• Create a new API Token with a descriptive name such as Privy Recovery - Expo
• Set Sign in Callback to auth.privy.io/api/v1/recovery/oauth/callback_icloud/YOUR_APP_ID/expo_ios, where YOUR_APP_ID is the ID of your Privy app. Apple will automatically prefix your URL with the protocol https://, so you should not set it yourself.
• Leave the rest of the fields as their default values

Web

• Create a new API Token with a descriptive name such as Privy Recovery - Web
• Set Sign in Callback to Post Message
• Leave the rest of the fields as their default values

4. Enter your CloudKit details in the Privy Dashboard

After setting up CloudKit, visit the Embedded wallets page of the Dashboard. In the Recovery tab, enable iCloud as a user-managed recovery option.

Enter your container ID and appropriate API token(s).

That's it! If you've configured your CloudKit production deployment with Privy correctly, you should be able to start using iCloud as a user-managed recovery method for embedded wallets.

FAQ

Should I implement recovery in my app or enable it in the Dashboard first?

You should enable iCloud as a recovery method for your app before beginning implementation, so it will work properly while you integrate and test. There are no negative side effects if you enable iCloud recovery in the dashboard but do not have it implemented.

Does my native iOS app need to be deployed to production to use CloudKit?

No, you're able to deploy a CloudKit container to Production out of band with the native app it was created from.

Will I have access to my user's recovery secrets?

No, only your users will have access to their stored recovery secrets. Even the CloudKit database is created by you, only a successfully authorized iCloud user can access their data.

Do I need to bring my own CloudKit configuration order to enable recovery?

Yes, there's no way to use an out-of-the-box Privy configuration for iCloud recovery.

Does Apple auth have to be enabled to enable to the recovery method?

No, they are decoupled.