Android Restore Credentials
Implement Android's Restore Credentials feature with androidx.credentials — the two-tier background/foreground restoration architecture, the createCredential fallback for devices without end-to-end encryption, sign-in and deletion flows with real Kotlin code, and the backend guidelines a client-side implementation must hand off to the developer, not implement itself.
A user restoring your app to a new phone shouldn't have to sign in again before their first notification arrives — Android's Restore Credentials API delivers silent sign-in during the OS restore itself, but only if a BackupAgent, a fallback for missing end-to-end encryption, and an explicit sign-out deletion path are all wired up correctly, and most implementations miss at least one.
Who it's for: Android engineers implementing silent re-authentication after a device restore, teams migrating off custom refresh-token-in-backup schemes to Google's Credential Manager API, developers integrating Restore Credentials alongside existing passkey or password auth, anyone confused about when BackupAgent.onRestoreFinished() fires versus onRestore()
Example
"Add Restore Credentials support to this Android app" → The two-tier architecture (background BackupAgent restoration plus a foreground Activity fallback) implemented against the actual allowBackup manifest setting, the createCredential-with-fallback pattern for devices lacking end-to-end encryption, working Kotlin for creation/retrieval/deletion, and an explicit backend-guidelines handoff reminding the developer their server still needs the matching implementation
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add android-restore-credentials# Android Restore Credentials
Implement Android's Restore Credentials feature through the Credential Manager API (`androidx.credentials`), so an app can silently log a user back in when they restore it on a new device — independent of the app's primary authentication method (passwords, passkeys, federated sign-in) and requiring no UI changes to existing sign-in flows.
**Scope:** this covers the Android client-side integration only. It does not implement server-side cryptographic validation — the developer must be told this explicitly after implementation (see Backend Guidelines below).
## Two-Tier Restoration Architecture
1. **Tier 1 (Primary — Background):** Runs automatically during device setup via the app's `BackupAgent.onRestoreFinished()` callback. Provides invisible restoration before the user opens the app for the first time, enabling background sync and notification delivery.
2. **Tier 2 (Secondary — Foreground):** Runs in the launcher `Activity.onCreate()` to catch failovers if background restoration didn't complete (dropped network, delayed restoration) or if `allowBackup` is disabled.
If `allowBackup` is `true` in the manifest, implement both tiers. Otherwise, implement only Tier 2. Never change the value of `allowBackup` to enable this feature — Restore Credentials works independently of it.Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
A client-side implementation guide for Android's Restore Credentials feature, from Google's own android/skills repository, built around the Credential Manager API (androidx.credentials). It implements the two-tier restoration architecture correctly: a primary background tier that fires from BackupAgent.onRestoreFinished() during device setup (invisible to the user, enabling background sync and notification delivery before the app is ever opened) and a secondary foreground tier in the launcher Activity that catches failovers when background restoration didn't complete or allowBackup is disabled — implementing only the tier that actually applies based on the manifest's allowBackup value, and never changing that value to enable the feature.
The scope is deliberately narrow and explicit: this is Android client-side integration only. The playbook works through creating a restore key (with the required fallback — retry createCredential with isCloudBackupEnabled = false if E2eeUnavailableException fires because the device lacks a screen lock or end-to-end encryption), signing in with a restore key on a new device, and deleting it correctly on sign-out with clearCredentialState. It closes with backend guidelines presented to the developer as a reminder rather than implemented directly — distinguishing restore credentials from user-visible passkeys in storage, preventing orphaned keys after an uninstall, and handling multi-device and remote session-invalidation cases server-side.
Quick Start
Step 1: Create a Project Folder
mkdir restore-credentials && cd restore-credentials
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Implement Restore Credentials
claude
Point Claude at your Android app and ask it to add Restore Credentials support. It will check allowBackup to determine which tiers to implement, wire up the Credential Manager creation/retrieval/deletion flow with the required exception fallback, and remind you explicitly which server-side pieces still need building.
Tips & Best Practices
- Always implement the
E2eeUnavailableExceptionfallback — a device without a screen lock or end-to-end backup encryption will throw it oncreateCredentialwithisCloudBackupEnabled: true, and skipping the retry silently leaves those users without a restore key at all. - Restore keys are per-package-name; an organization with multiple apps sharing user accounts needs a separate restore key generated for each app.
- Distinguish restore credentials from user-created passkeys in your backend storage from day one — they use the same underlying WebAuthn mechanism, but restore credentials must stay hidden from any user-facing passkey-management UI.
Limitations
- Client-side only by design — the matching server-side cryptographic validation and relying-party setup is explicitly out of scope and must be implemented separately, following the backend guidelines this playbook hands off.
- Requires Android 9 (API 28)+, Google Play services core 24220000+, and
androidx.credentials1.5.0+; older devices fall back to the app's normal sign-in flow. onRestoreFinished()(notonRestore()) is the callback that reliably fires for any kind of backup restore — using the wrong callback silently breaks the background tier without an obvious error.