Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Set Up Recovery – 1auth
Skip to content

Set Up Recovery

This guide is about setting up a recovery backup ahead of time — not the act of recovering an account. You decide when to offer it; the SDK handles the rest.

1auth accounts are secured by a passkey stored on the user's device or password manager. If that passkey is ever lost, the account is unreachable unless the user prepared a backup first. So your app prompts the user to create one: a short recovery passphrase and an encrypted backup file. Together they can restore the account even if every passkey is gone.

Whether and when to offer this is your app's call — 1auth never prompts on its own. When you're ready, trigger the flow with a single call:

const { completed } = await client.setupRecovery()

When to prompt

The backup is optional, and it's entirely up to your app to decide when to surface it — a natural moment is right after sign-up, or the first time a user holds a meaningful balance. setupRecovery() resolves with { completed } so you can record that the user finished (and avoid nagging them again):

const { completed } = await client.setupRecovery()
if (completed) {
  // mark the onboarding step done for this user
  await markRecoveryBackedUp()
}

completed is false if the user closes the dialog without finishing — you can re-prompt later.

What the user sees

After you call setupRecovery(), the dialog walks the user through the backup inside the secure 1auth iframe:

  1. Backup your account — an intro nudge (with an "Are you sure?" step if they decline).
  2. Verify with their passkey — a Face ID / Touch ID prompt derives the recovery key from the passkey (the key never leaves the device).
  3. Recovery passphrase — a short passphrase to copy and store somewhere safe (e.g. a password manager).
  4. Backup file — an encrypted file to download and store separately.
  5. Done — both pieces are required to recover, so they're stored apart.
Backup your account  →  Verify (passkey)  →  Setup account recovery
                                              ├─ 1. Recovery passphrase  (copy)
                                              └─ 2. Backup file          (download)
                                              →  Account recovery completed

How it works

  • The recovery key is an ECDSA key derived from the user's passkey via the WebAuthn PRF extension — 1auth's servers never store recovery material.
  • The downloaded file is the recovery key encrypted with AES-256-GCM; the recovery passphrase is the key that decrypts it.
  • Because the passphrase and the file are stored separately, neither one alone is enough — an attacker would need both to recover the account.

Next steps