Restore app credentials when setting up a new device

Credential Manager's Restore Credentials feature allows users to restore their app accounts when setting up a new device. This API is in developer preview and available on all devices that have Android 9 or higher and Google Play services (GMS) Core version 242200000 or higher. The benefits of the Restore Credentials feature includes:

Seamless user experience: Users can restore their app account without needing to manually sign in to each individual app.
Increased user engagement: Users are more likely to continue using your app if they can restore their account when setting up a new device.
Reduced development effort: the Restore Credentials feature is integrated with Credential Manager, so developers who already support passkeys can add credential restoration capabilities.

How it works

You can use Restore Credentials to create, get, and clear the relevant credentials.

Create the Restore Credential: When the user signs in to your app, create a Restore Credential associated with their account. This credential is stored locally and synced to the cloud if the user has enabled Google Backup and end to end encryption is available (apps can opt out of syncing to the cloud)
Get the Restore Credential: When the user sets up a new device, your app can request the Restore Credential from Credential Manager. This lets you sign the user in automatically without requiring any additional input.
Clear the Restore Credential: When the user signs out of your app, you should delete the associated Restore Credential.

The Restore Credentials feature can integrate smoothly with backend systems that have already implemented passkeys. This compatibility stems from the fact that both passkeys and restore keys (credential type used by the Restore Credentials feature) adhere to the same underlying technical specifications. This alignment makes sure that the Restore Credentials process can effectively retrieve and reinstate user credentials stored in passkey-enabled systems, providing a consistent and user-friendly experience across different platforms and authentication methods.

Credential Manager bottom sheet — **Figure 1.** Diagram that depicts restoring an app data to a new device using a restore credential, including creating the credential, initiating a restore flow, and automatic user sign-in

Implementation

The Restore Credentials API is available through the Credential Manager Jetpack library. To get started, follow these steps:

Add the Credential Manager dependency to your project.

// build.gradle.kts
implementation("androidx.credentials:credentials:1.5.0-alpha03")

Create a CreateRestoreCredentialRequest object.

Note: Set the isCloudBackupEnabled flag as true to enable the auto backup of the restoreKey (if the user has Google Backup enabled and end to end encryption is available). Set it to false if you want the restoreKey to be stored locally and not in the cloud.

Call the createCredential() method on the CredentialManager object.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)RestoreCredentialsFunctions.kt

This generated restore credential is a type of webauthn credential, and is known as a restore key.

When the user sets up a new device, call the getCredential() method on the CredentialManager object.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)RestoreCredentialsFunctions.kt

When the user signs out of your app, call the clearCredentialState() method on the CredentialManager object.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)RestoreCredentialsFunctions.kt

If you're using a backup agent, perform the getCredential part within the onRestore callback. This makes sure that the app's credentials are restored immediately after the app data is restored.

Frequently asked questions

Q1. What is the difference between a restore key and a passkey?

A restore key functions similarly to a passkey but is specifically designed for account restoration on new devices. When you use a password manager such as Google Password Manager to authenticate, your usable passkeys and passwords are displayed, while the restore key is not, as it's not intended for regular sign-ins.

Q2. Is a restore key a one-time use credential?

No, a restore key isn't a one-time use credential. Credential Manager is stateless and unaware of user activity, so it cannot automatically delete the key after use.

Restore keys are only removed in the following situations:

System-level actions: Users uninstall the app or clear its data.
App-level calls: You programmatically delete the key by calling CredentialManager#clearCredentialState() when you handle user log out in your app's code.

Q3. Does the Restore Credentials feature only work for a new device?

Yes, this feature is designed for the initial setup of a new Android-powered device, as it is tied directly to the system's Backup and Restore functionality.

Q4. Can I use Restore Credentials to silently sign in a user to any device that has the same Google Account logged in?

No, the Restore Credentials feature is not intended to be used for general sign-in across devices. It only works in one specific scenario: when a user is setting up a new device by restoring a backup from their old device. Both devices must be linked to the same Google Account for this one-time restore process to succeed.

Q5. My organization has one main app and multiple sub-apps. Can one restore key work for all of these apps?

No. A restore key is tied to an application's unique package name. Since your main app and each sub-app have different package names, you need to create a separate restore key for every app.

Q6. Is a passkey required to create a restore key for a user's account?

No, a passkey is not required. The ability to create a Restore Key is independent of the user's sign-in method. Its purpose is to save the user's current authenticated state. As long as the user is actively signed in to your app, you can generate a Restore Key for them.

Q7. Can the user delete the restore key?

No, the user has no direct control over the restore key. The app logic is responsible for managing restore keys.

For security, we recommend that the app automatically deletes the key whenever a user signs out. This makes sure that the next time they open the app on that same device, they are properly signed out and will be prompted to sign in again.

Q8. Can I use Restore Credentials without setting allowBackup to true in my manifest?

Yes, the Restore Credentials feature works regardless of whether allowBackup is set to true or not.

Q9. How would Restore Credentials work for users who have multiple logged-in accounts on the same app?

The Restore Credentials feature is designed to work with only one account at a time.