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

App-origin accounts configure recovery when the account is created. The docs client uses a verified-identity fallback, so a user who loses every passkey can verify the same email or OAuth identity and register a new passkey for the same docs-hostname account.

setupRecovery() is a readiness check in app-origin mode. It validates the current origin-bound session and resolves once recovery is configured for that account:

const { completed } = await client.setupRecovery()

App-origin recovery

Log in to check recovery 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; it does not move recovery into the centralized passkey service namespace.

Check readiness

Call setupRecovery() only after login or account creation:

const auth = await client.authenticate({ flow: 'login' })
if (!auth.success) throw new Error(auth.error?.message ?? 'Login failed')
 
const { completed } = await client.setupRecovery()
if (completed) {
  await markRecoveryReady(auth.session.accountAddress)
}

For app-origin accounts, completed: true means the SDK validated a fresh bearer for the exact origin, RP ID, and account namespace. The method does not open the centralized recovery-passphrase or backup-file flow.

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. It never falls back to a centralized-RP credential.

Next steps