Password reset

A user who forgot their password asks for a reset email, opens the link, and picks a new password. Finishing the reset signs them in on that device and ends every other session they had, in case someone else knew the old password.

This guide starts from a finished quickstart running against Orvano on your machine; the reset email lands in the local inbox at http://localhost:8025. It uses the same kind of landing page as Email verification, so read that first.

1. Ask for the email

account.createRecovery needs no session. It always answers the same way, whether or not the email has an account, so nobody can use your reset form to find out who signs in to your app. Tell the user “If that email has an account, we sent a link”, whatever happened.

JavaScript

await orvano.account.createRecovery({ email, redirectUrl: `${location.origin}/reset.html` })

Next.js

'use server'
await (await orvano()).account.createRecovery({ email, redirectUrl: `${appUrl}/auth/reset` })

Flutter

await orvano.account.createRecovery(
  CreateRecoveryRequest(email: email, redirectUrl: 'https://app.example.com/auth/reset'),
);

The redirectUrl must be https on one of the project’s web platforms, or http on localhost. A reset link signs the user in, so Orvano never sends one to a custom app scheme; a Flutter app on iOS or Android needs https app links. The link works once, for 1 hour.

Open http://localhost:8025: you should see “Reset your password” with a Reset password button.

2. Set the new password

The landing page asks for the new password, then finishes the link with it when the user selects Continue:

JavaScript

const result = await orvano.client.redeemLink(undefined, { password: newPassword })
// result.user is signed in now

Next.js

'use client'
// app/auth/reset/page.tsx, with the Referrer-Policy header from the verification guide
async function onContinue(newPassword: string) {
  await orvano.client.redeemLink(undefined, { password: newPassword })
  router.push('/')
}

The route handler sets the new session cookies.

Flutter

await orvano.client.handleLink(link, password: newPassword);

What finishing the reset does (account.completeRecovery):

• sets the new password, after checking it has 8 to 256 characters (invalid_password leaves the link usable, so the user can try again);
• ends every other session of the user, and starts a new one here;
• marks the email verified, since the user just proved they read it.

A used, expired, or replaced link gets invalid_email_token, and a blocked user gets user_blocked.

Send a reset from your server

Support tools can send a user the reset email with users.createRecovery and an API key with users.write. See Manage users with an API key.