Reset a forgotten password

Recover access when the user forgot the password. Routes sit on the management group (facade default /identity). Mail is sent only for a confirmed account. The forgot endpoint always returns 200.

Seamless reset UX is host-owned. AuthEndpoints calls IEmailSender<TUser>.SendPasswordResetCodeAsync with an HTML-encoded Base64Url reset code. You do not need a package change to improve the client flow.

Forgot and reset do not require antiforgery or a session. Reset body is Identity-shaped: { "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: POST /identity/login (LoginCookie). Persistent cookie: ?useSessionCookies=false. See Cookie auth.
8. On invalid or unknown token or user, expect 400 validation problem (for example InvalidToken). Do not reveal whether the email exists from the forgot step.

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

• Identity management
• Cookie auth
• Register a confirmed account