Reset a forgotten password

Use these steps when a user forgot their password. The routes are on the management group (facade default /identity). They need no CSRF token and no session.

POST /identity/forgotPassword always returns 200. AuthEndpoints sends mail only when the account exists and its email is confirmed. It calls IEmailSender<TUser>.SendPasswordResetCodeAsync with an HTML-encoded Base64Url reset code. You build the reset screen and the mail template. The reset body is Identity's ResetPasswordRequest: { "email", "resetCode", "newPassword" }.

Video

Steps

1. Collect the account email on a Forgot password screen.
2. POST /identity/forgotPassword with body { "email" }.
3. On 200, show Check your email (same copy for known and unknown addresses). Then use one of the host patterns below for the reset screen.
4. Build the reset mail in your IEmailSender<TUser> implementation. AuthEndpoints passes HtmlEncoder.Default.Encode(base64UrlCode) into SendPasswordResetCodeAsync. Decode HTML entities before the user copies the code or before you put it in a link query. If you embed the code in HTML again, re-encode for markup.
5. Collect email, reset code, and new password on a Reset password screen.
6. POST /identity/resetPassword with body { "email", "resetCode", "newPassword" }. Submit the Base64Url value (not the Identity raw token).
7. On 200, sign in with the new password. See Sign users in.
8. On 400 validation problem InvalidToken, show a generic error. AuthEndpoints returns that code for a bad code, an unknown email, and an unconfirmed email alike. Password-rule failures return their own codes, such as PasswordTooShort.

Host patterns after forgot 200

Same-session auto-nav (safer default)

After forgot returns 200, navigate the SPA to the reset page with email only prefilled (query string or sessionStorage). The user pastes resetCode from the mail.

No reset token in the URL. Fits the same browser that started forgot.

Email deep link (cross-device)

In SendPasswordResetCodeAsync, include a host-owned link to your reset page with email and resetCode (or code) query params. Still show the code in the mail as a paste fallback.

Stock forgot uses SendPasswordResetCodeAsync, not SendPasswordResetLinkAsync. A clickable link is entirely your mail template (or a custom pipeline you build). Query tokens can leak through history, Referer, and logs. Prefer same-session auto-nav when the user resets on the same device.

Related

• Sign users in
• Register users
• Identity management module