Backup and Recovery

Enroll a backup login method on every account, preferably an email address, and know what recovery looks like for a user who loses their device or passkey.

Every account should have a backup login method, preferably an email address. This gives users a way to regain access if they lose a device or can no longer use their primary authentication method.

Rain cannot reset a user account or move funds on the user’s behalf. If a user loses access to every login method associated with the account, Rain cannot restore access to the wallet.

How recovery works

The wallet is not stored on the user’s device. Losing a device does not mean losing the wallet. Recovery depends on whether the user can still authenticate to the account.

Situation	What the user does	What they need
New or replacement device, account created with email or phone	Log in using the same email address or phone number	Access to the email inbox or phone number
New or replacement device, synced passkey available	Log in with the existing passkey	Access to the passkey through the user’s passkey provider
Passkey unavailable, backup contact enrolled	Log in with a code sent to the backup contact, then add a new passkey	Access to the backup email address or phone number
Passkey unavailable, no backup contact, recovery phrase or private key previously exported	Import the recovery phrase or private key into a compatible wallet	The exported recovery phrase or private key
Passkey unavailable, no backup contact, nothing exported	The wallet cannot be recovered	—

Recommended setup

Prompt users to add a backup email address during account setup, and require a backup method before they store meaningful value in the wallet.

Coming at GA: a full recovery model with a dedicated setup guide and a step-by-step recovery guide for end users and support agents.

Enroll a backup method

The recommended backup setup depends on how the account was created.

• Accounts created with email or SMS already have a contact method associated with the account. Users can also add a passkey with addPasskey for faster authentication. For additional protection against losing access to the email address or phone number, see key export.

• Accounts created with a passkey do not initially have an email address or phone number associated with the account. Prompt the user to add a verified email address, preferably, or phone number immediately after sign up.

Attach a verified contact to a passkey account

Available on iOS and Android, on a live session. The flow mirrors login: send a code to the contact, confirm it, and the contact is stored as verified and becomes a login method for the account.

1. Collect the contact

   Ask for an email address. Email is preferred over a phone number because users keep email addresses across carriers, countries, and phone numbers, and because an inbox is easier to regain access to.

2. Send the verification code

   iOS

   try await wallet.sendContactVerificationCode(to: .email("[e-mail]"))
   

   Requires a live session; without one the call throws RAIN_201. Malformed input throws RAIN_102 before any request is made.

3. Confirm the code

   iOS

   do {
       try await wallet.confirmContactVerification(code)
   } catch let error as RainError where error == .invalidLoginCode {
       // RAIN_203: the code was rejected (wrong, expired, or locked after 3 misses).
       // The app can't tell which, so let the user retype it and offer "Send a new code".
   }
   

   On success the contact is verified and attached. The next time this user is on a new device, sendLoginCode with the same address logs them into this account.

   The account now has two login methods. Reflect that in your UI, for example a Login methods section in settings showing the passkey and the verified email.

A contact identifies one account. Attach a contact that isn’t already used to log in to another account; otherwise the user ends up unable to tell which wallet a code will open.

When to prompt for backup authentication

• Immediately after passkey sign up. After signUpWithPasskey succeeds, prompt the user to add and verify an email address. Let users skip this step, but prompt them again later if they still have only one authentication method.

• Before the wallet holds meaningful value. Before the first deposit or before the user funds a card, require a backup authentication method if the account still has only one way to log in.

• In account settings. Show the authentication methods associated with the account and let users add email, phone, and passkey methods.

• When offering key export. Treat key export as an advanced recovery and portability option, not the default backup method. Make the security tradeoff explicit: once a user exports a recovery phrase or private key, anyone who obtains it can control the wallet, and Rain cannot protect or recover that exported secret.

Support runbook

When a user loses access to their wallet, first identify which authentication methods are still available.

1. Confirm the authentication methods on the account. Determine how the user originally signed up and whether they added an email address, phone number, or passkey. During beta, Rain does not expose account lookup information to partners, so your support team should rely on your own records of the methods the user enrolled.
2. Device lost, email or phone still available. Have the user install your app on a new device and log in with the same email address or phone number. They will regain access to the same wallet, and getWalletAddress will return the same addresses.
3. Passkey unavailable, backup contact available. Have the user authenticate using the backup email address or phone number, then use addPasskey to register a new passkey.
4. No authentication method is available. Ask whether the user previously exported their recovery phrase or private key. If they did, they can import it into a compatible wallet and regain control of their funds. If they did not, neither Rain nor your application can recover access to the wallet.
5. The wallet owns a Rain collateral contract. For Rain managed programs, funds used for card collateral may remain in the user’s collateral contract even if the user loses access to the wallet. Contact Rain for assistance with the contract and see Changing the owner wallet.

What’s next

Key export

The last-resort backup: recovery phrase and private keys.

Authentication options

Login flows the recovery paths rely on.