POST
Reset password

Overview

Confirms a password reset by submitting the 6-digit code received via POST /forgot-password along with the new password. On success:
  1. The OTP row is marked consumed.
  2. The new password is hashed with argon2id and persisted.
  3. All active refresh tokens for the user are revoked — every device gets logged out. This is intentional: if the reset request was attacker-driven, the legitimate user still controls their email, but we cannot trust any session that might predate the request.
The client must then call POST /login with the new password to start a fresh session. Same 5-attempt cap and INVALID_CODE / CODE_EXPIRED semantics as /verify-email.

Authentication

None required.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 200 OK

Example response

Error responses

Example error — 401 INVALID_CODE

Side effects

  • Consumes the otp_codes row.
  • Updates users.passwordHash to the new argon2id hash.
  • Updates all matching refresh_tokens rows to revokedAt = now — every active session is killed.
  • Sets users.emailVerified = true if it was not already — the reset code proves control of the inbox, so the new password is not stopped by login’s EMAIL_NOT_VERIFIED gate.

See also

curl