Upgrade to 4.0Changelog
Guides

Change a user's email or password

Read account info, change the password, and change the email after the user confirms the new address.

A signed-in user changes their email or password through /auth/manage/info on the password facade. POST requires a CSRF token in the RequestVerificationToken header and a fresh ReAuth proof. The body is Identity's InfoRequest: { "newEmail"?, "newPassword"?, "oldPassword"? }.

Read the account info

Send GET /auth/manage/info. The response is { "email", "isEmailConfirmed" }. This route needs no CSRF token and no ReAuth.

Change the password

  1. Complete step-up. See Require step-up before sensitive actions.
  2. Send POST /auth/manage/info with { "oldPassword", "newPassword" } and the CSRF header.
  3. Check the response:
    • 200 { "email", "isEmailConfirmed" }: the password changed.
    • 400 validation problem OldPasswordRequired: the request had newPassword but no oldPassword.
    • 400 validation problem PasswordMismatch: oldPassword was wrong. Password-rule failures return their own codes.

A user who forgot the current password uses Reset a forgotten password instead.

Set a first password

An account created from an emailed code, a passkey, or an external login has no password. POST /auth/manage/info cannot add one. Use POST /auth/manage/password.

  1. Complete step-up. An account with no password, authenticator, or passkey can use an emailed code when email-code step-up is mapped. See Require step-up before sensitive actions.
  2. Send POST /auth/manage/password with { "newPassword" } and the CSRF header.
  3. Check the response:
    • 200 with an empty body: the password is set. Password login then works. The security stamp rotates, so other sessions that check the stamp end. The acting cookie session stays signed in and needs a new ReAuth proof for the next sensitive action.
    • 400 validation problem UserAlreadyHasPassword: the account already has a password. Change it with POST /auth/manage/info.
    • 400 validation problem PasswordRequired: newPassword was missing or empty. Password-rule failures return their own codes.
    • 404: password sign-in is not mapped, so this host has no password login to use the new password.

MapPasswordAuth, MapAccountManagementEndpoints, and MapIdentityManagementApi map this route. The notice goes through IAccountSecurityEmailSender<TUser>. The default implementation only logs. Register an implementation to send the mail. The password is not included.

Change the email

  1. Complete step-up.
  2. Send POST /auth/manage/info with { "newEmail" } and the CSRF header.
  3. The response is 200 and still shows the old email. AuthEndpoints sends a change-email link to the new address through IEmailSender<TUser>.SendConfirmationLinkAsync.
  4. The user opens the link: GET /auth/confirmEmail?userId=...&code=...&changedEmail=.... The email and the user name change only now.
  5. With EmailConfirmation.ConfirmEmailRedirectUri set, the link redirects with flow=change-email and status=confirmed or status=failed. Without it, the link returns 200 text or 401.

An invalid newEmail returns a 400 validation problem InvalidEmail. You can send newEmail and newPassword in one request. AuthEndpoints changes the password first.

Know the limits

  • POST /auth/manage/info cannot set a first password on an account that has none. It returns OldPasswordRequired. Use POST /auth/manage/password when password sign-in is mapped.
  • No endpoint deletes an account.