Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Lost Passkey Recovery

If a user loses their phone, gets a new laptop, or their passkey simply stops working, they can recover their account through guardians — trusted backup signers that can authorize adding a new passkey.

Guardians

A guardian is someone (or something) that can vouch for the account owner during recovery. 1auth supports two types:

  • Google account — The user links their Google account during setup. During recovery, they sign in with Google to prove their identity. This is the recommended default.
  • Personal backup — The user creates a passphrase-based backup key. The passphrase never leaves the browser — it's used locally to derive a signing key. This works fully offline, but the user must remember or securely store the passphrase.

Both guardians can be set up together with a threshold: require one (either guardian can authorize recovery) or both (both must approve). Most users should use a threshold of one for simplicity.

Setting Up Recovery

Users set up recovery directly in the 1auth dialog — the same popup they use to sign in and approve transactions. The setup flow walks them through three steps:

  1. Link a Google account — Sign in with Google to register it as an external guardian. This binds the user's Google identity to the account on-chain.
  2. Optional personal backup — Create a passphrase-based backup key, or connect an external wallet as a second guardian
  3. Confirm with biometrics — Approve the guardian configuration with Face ID, Touch ID, or another authenticator. The setup is deployed on-chain across all supported chains.

Once configured, the user's account can be recovered even if their original passkey device is completely lost.

Recovery is scoped to the account in your app — guardians configured in one app do not recover a user's account in another. See Per-App Accounts.

Recovering an Account

When a user needs to recover, they open the recovery flow from any app that integrates 1auth:

  1. Identify their account — Enter their account address or username. The system looks up the guardian configuration on-chain.
  2. Register a new passkey — Create a new passkey on their current device using Face ID, Touch ID, or another authenticator
  3. Prove their identity — Sign in with Google (or enter their passphrase) to authenticate with the guardian. The guardian verifies this against the identity linked during setup.
  4. Automatic execution — The recovery transaction is submitted across all chains where the account is deployed. Once confirmed, the user can sign in with their new passkey immediately.

The entire process takes a few minutes. No funds are at risk during recovery — the account remains secure and unchanged until the recovery transaction completes.

For Developers

Experimental cross-origin integrations can open the account management dialog:

const result = await client.openAccountDialog();
if (!result.success) throw new Error(result.error.message);

This opens the 1auth dialog where users can configure their guardians. App-origin clients return APP_ORIGIN_FLOW_UNSUPPORTED before opening UI; use the app-origin recovery APIs and your own account-management UI instead.

If a user has lost their passkey and needs to recover, the recovery flow is accessible from the 1auth login dialog — users click "Recover" to start the process. No additional SDK integration is needed.