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

Account Recovery

setupRecovery() opens an interactive backup flow for the signed-in app-origin account. The user explicitly approves a WebAuthn PRF assertion on your app's top-level page, copies a recovery passphrase, initiates an encrypted 1auth.recovery-key file download, and confirms the backup steps:

const result = await client.setupRecovery()
if (!result.completed) {
  if (result.error.code === 'USER_CANCELLED') {
    // The user closed or cancelled the backup flow.
  } else {
    throw new Error(result.error.message)
  }
}

App-origin recovery

Log in to create a recovery backup for this docs-hostname account.

Configure the client

Choose the recovery fallback when constructing the same app-origin client used for signup and login:

const client = new OneAuthClient({
  providerUrl: 'https://passkey.1auth.app',
  clientId: 'your-app-id',
  recovery: { fallback: { type: 'verified-identity' } },
})

The browser hostname remains the WebAuthn RP and account namespace. clientId selects app metadata only.

Run the backup flow

Call setupRecovery() only after login or account creation, and keep the UI in a pending state until its promise settles:

const auth = await client.authenticate({ flow: 'login' })
if (!auth.success) throw new Error(auth.error?.message ?? 'Login failed')
 
setRecoveryStatus('pending')
const result = await client.setupRecovery()
if (result.completed) {
  setRecoveryStatus('success')
} else if (result.error.code === 'USER_CANCELLED') {
  setRecoveryStatus('cancelled')
} else {
  setRecoveryError(result.error.message)
}

completed: true means the user approved the real app-origin assertion, copied the passphrase, initiated the encrypted backup-file download, and pressed Finish. completed: false is not always cancellation: only error.code === 'USER_CANCELLED' means the user dismissed the flow. Treat every other error code, including AUTH_FAILED, as a failed setup and show its error message.

Keep the two backup parts separate

The passphrase decrypts the downloaded file. Ask the user to keep them in different secure locations. The SDK keeps the assertion, PRF output, guardian private key, passphrase, and encrypted-file key in browser memory only. These secrets are never sent to your server or 1auth, placed in URLs or browser storage, written to logs, or delivered through postMessage.

Clipboard access happens only when the user clicks Copy passphrase. The encrypted 1auth.recovery-key file is safe to store, but it is useless without the separately saved passphrase.

What happens after passkey loss

  1. The user starts login and verifies the same configured email or OAuth identity in 1auth's identity UI.
  2. 1auth finds the existing account in the current app-origin namespace.
  3. The SDK runs recovery registration in your app's top-level page.
  4. The new passkey is activated for the existing smart account.
  5. The SDK stores a fresh app-origin session for subsequent signing.

The passkey service may render identity and recovery instructions, but the WebAuthn registration ceremony stays on the integrator's top-level origin.

Next steps