Account API
Password changes, forced rotation, and session revocation
The account API contains the signed-in user's credential change operation. A successful password change signs the browser out through the change-password page because the change revokes every live session for that account.
POST /api/account/password
Authentication: An existing session is required. Success: 200.
| Field | Type | Required? | Constraints |
|---|---|---|---|
currentPassword | string | Yes | 1–128 characters; compared with the current bcrypt hash. |
newPassword | string | Yes | 14–128 characters; must include uppercase, lowercase, digit, and special character. |
The 14-character rule applies together with all four character-class requirements. The new password must also differ from the current password.
curl -X POST http://localhost:3000/api/account/password \
-H 'content-type: application/json' \
-H 'cookie: next-auth.session-token=SESSION' \
-d '{"currentPassword":"OldPassword2026!","newPassword":"NewHarborPassword2026!"}'Success:
{"data":{"changed":true}}The endpoint allows five attempts per user in a 15-minute window. It returns:
| Status | Meaning |
|---|---|
| 200 | The password was changed. |
| 400 | The body is malformed, a field fails validation, or the new password equals the current password. |
| 401 | No session exists. |
| 403 | The current password does not match. |
| 429 | The per-user five-attempt, 15-minute limit was exceeded. |
| 500 | An unexpected server error occurred; details stay in the operational log. |
On success, the route stores the new bcrypt hash, clears mustChangePassword, and increments sessionVersion. The JWT callback then revokes every live token carrying the previous version, including the caller's token when it refreshes. The change-password page signs the caller out immediately and sends them back to /login.
The route emits password_change_success on success, password_change_failure for validation failures, a current-password mismatch, or an unchanged password, and password_change_rate_limited when the rate limit is reached. Accounts with mustChangePassword are subject to the password rotation gate.