​

Conventions

The flows are numbered (BF-1, BF-2, …) and referenced from code and other docs. Each section below covers purpose, what’s non-obvious, and where the iOS and Android implementations diverge — not a step-by-step script. The authoritative sequencing lives in the client code; this page exists to explain why a flow looks the way it does.

​

BF-1: Backup Creation

When. A user finishes onboarding and creates their first backup, picking one or two recovery methods. Non-obvious. The client generates a fresh Backup Encryption Keypair at this moment, encrypts the Sealed Backup, encrypts the keypair with the Factor Secret of each enrolled Main Factor, and then discards the keypair’s secret. Only the public key is retained locally so subsequent sync operations can re-encrypt new Sealed Backups without authenticating a Main Factor. This is what makes background sync (BF-4) possible. A Sync Factor is also generated at creation and registered with the Backup Service in the same /v1/create call, so the device is immediately authorized to push updates. OIDC + Passkey one-tap enrollment. When the user enrolls both a Passkey and an OIDC factor (Google/Apple) at creation, the client takes advantage of a merged Turnkey passkey challenge: the Passkey signs both a Backup Service challenge and a Turnkey activity stamp in a single user gesture. This is also the pattern used in BF-3 when adding an OIDC factor to an existing Passkey-only account. Cross-platform. iOS and Android diverge only in the platform-specific factor enrollment (Passkey ceremony, OIDC sign-in SDK). The Bedrock-side sealing and backup-service interaction are identical.

​

BF-2: Backup Retrieval

When. A user signs into World App on a new device. Non-obvious. Retrieval (or previously “Recovery”) is the most architecturally distinct flow because the user has no local state. The client has to bootstrap from a single Main Factor. The client identifies the backup by presenting the Main Factor’s public identifier (passkey credential ID, OIDC sub, or Keychain public key) — the Backup Service has a reverse lookup table that maps these to a backup_id. Once the backup is located, the user authenticates the factor and the Backup Service returns the Sealed Backup together with the metadata. After the backup is decrypted, the client generates a fresh Sync Factor for the new device and registers it via /v1/add-sync-factor. This call uses a short-lived sync_factor_token issued by /v1/retrieve/from-challenge, which lets the client add the new device authorization without re-prompting for a Main Factor. OIDC recovery quirk. For OIDC factors, decrypting the Backup Encryption Keypair requires the Factor Secret held by Turnkey. The user authenticates to Turnkey via OIDC; Turnkey’s enclave verifies the OIDC token and the user’s identity before exporting the secret to the client. This is why OIDC recovery requires a network round-trip beyond the one to the Backup Service.

​

BF-3: Adding a Main Factor

When. A user adds a second (or third) recovery method from Settings. Non-obvious. Adding a factor does not require re-encrypting the entire backup. The client only needs to encrypt the existing Backup Encryption Keypair with the new Factor Secret and append the resulting Encrypted Backup Encryption Keypair to the metadata. This is the entire point of the keypair indirection layer (see Layered Encryption Model). To add an OIDC factor with a Passkey already enrolled, the merged Turnkey passkey challenge from BF-1 is reused — one passkey tap authorizes both /v1/add-factor on the Backup Service and the Turnkey activity that creates the OIDC provider. Currently disabled. Adding a Passkey when an OIDC factor exists is not supported today. Removing a Passkey while an OIDC factor exists is also not supported, because the Passkey is the fallback path for Turnkey when the Sync Factor’s Turnkey credentials are no longer valid (see Unauthorized Device).

​

BF-4: Backup Sync

When. The user takes an action that produces a new file (e.g., orb verification yields a new PCP) or modifies the credential vault. Non-obvious. Sync runs silently — it only uses the Sync Factor, not a Main Factor. The client retains the public half of the Backup Encryption Keypair from creation/recovery, which is enough to re-encrypt the new Sealed Backup without unlocking any factor secret. The flow is gated by the manifest hash. If the local manifest is stale (the user updated their backup on another device), the sync attempt fails with manifest_hash_mismatch and the UI escalates to BF-5.

​

BF-5: Remote-Update Detection

When. App launch, and on demand from sync failures. Non-obvious. This is the only flow that prompts re-authentication of a Main Factor outside of explicit user intent. Because background sync cannot fetch encrypted backup contents (the Sync Factor can’t decrypt), reconciling a remote update requires a Main Factor. The client simply fetches the remote manifest hash; if it doesn’t match the local hash, the UI presents a recovery-style prompt and the user re-authenticates a Main Factor to download the updated backup. After download, local sync resumes normally.

​

BF-6: Multi-Device Sync

This is not a separate flow but a consequence of BF-4 and BF-5 interacting. See Advanced Topics — Multiple Device Sync.

​

BF-7: Factor Deletion

When. The user removes a recovery method from Settings. Non-obvious. Two systems need updating: the Backup Service (remove from Backup Metadata) and Turnkey (remove the corresponding OIDC provider, or delete the sub-organization if it’s the last OIDC factor). Both deletions happen using the Sync Factor, not a Main Factor — Turnkey policy explicitly authorizes the Sync Factor for these specific deletion activities (see Components & Parties — Turnkey). This avoids a passkey prompt on every Settings interaction. Failure handling. If the Sync Factor is no longer valid in Turnkey (PUBLIC_KEY_NOT_FOUND — see Unauthorized Device), the client falls back to the user’s Passkey to perform the Turnkey operation. This is one of the reasons a Passkey is currently required to manage other factors. Last factor. Deleting the last Main Factor cascades into BF-8.

​

BF-8: Backup Deletion

When. The user removes their last Main Factor, or initiates full account deletion in World App. Non-obvious. Deletion clears state across three places — the Backup Service (metadata + sealed blob + factor lookup), Turnkey (entire sub-organization, if one exists), and local device (Sync Factor keypair, plus the iCloud Keychain factor on iOS). All three deletions are issued from the client with retries; failures are logged but do not block the user-visible “deleted” outcome, because the Backup Service’s deletion is authoritative.

​

BF-9: Disaster Recovery via /v1/reset

When. The user has lost every Main Factor and every Sync Factor but still controls the original device (and therefore the Root Key). This is the last-resort path; see Disaster Recovery via /v1/reset for the full rationale and preconditions. Non-obvious. This is a destructive wipe, not a recovery of backup contents. This process clears the backup so the user can re-enroll from scratch. It’s authorized by the Backup Account Key the user reproduces locally, so nothing here depends on a Main or Sync Factor:

1. The Backup Service /v1/reset deletes the metadata, sealed blob, and factor-lookup entries. This deletion is authoritative.
2. The Turnkey sub-organization is torn down. The client submits a deleteSubOrganization activity stamped with the Backup Account Key acting as the break_glass_user.

​

BF-10: Turnkey Account Migration

When. After every login, and periodically thereafter. Not user-initiated. Non-obvious. This is housekeeping, not a user flow, but it is the only mechanism that can correct a Turnkey sub-organization created by an older client or that has unexpectedly drifted as nothing server-side has the authority to write to it. The client calls Bedrock’s TurnkeyManager.run_migrations with the Sync Factor and, when available, a Main Factor. Migrations mostly require a Main Factor to write, which the client does not have outside a login. So if a Main Factor is required, the user is prompted to authenticate, similar to the Authorize Device flow. See Turnkey Migrations.