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.

1. **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)
2. **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.
3. **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](https://developer.android.com/static/identity/sign-in/images/restore-credentials-flow.svg) **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 **Note:** Restore keys are the sole credential type supported for this feature. Other credential types, such as passwords, security tokens, or biometric data, are not compatible.

## Implementation

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

1. Add the following dependencies to your app module's build script, to use the latest version of the [Credential Manager library](https://developer.android.com/jetpack/androidx/releases/credentials):

### Kotlin

```kotlin
dependencies {
    implementation("androidx.credentials:credentials:1.6.0-rc01")
}
```

### Groovy

```groovy
dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
}
```

1. 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.
2. 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)

   This generated *restore credential* is a type of webauthn credential, and is
   known as a *restore key*.
3. 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)

4. 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)

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.
| **Note:** Restore Credentials does not handle the scenario where an app is reinstalled on the same device. Uninstalling an app is interpreted as an intent to delete the corresponding restore key from that device.

## 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()`](https://developer.android.com/reference/androidx/credentials/CredentialManager#clearCredentialState(androidx.credentials.ClearCredentialStateRequest)) 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.