POST /v1/auth/password/reset
Consume a password reset token and set the new password. Revokes every active session for the user — a password reset is a "potentially compromised" signal.
::: tip Auth Required: none. The token IS the credential. :::
Request
POST /v1/auth/password/reset
| Header | Required | Notes |
|---|---|---|
Content-Type: application/json | yes | — |
Body
{
"token": "abc...32_byte_base64",
"new_password": "a-fresh-secret-with-at-least-12-chars"
}
| Field | Type | Required | Notes |
|---|---|---|---|
token | string | yes | The raw token from the reset email. |
new_password | string | yes | 12–256 chars. |
Response
204 No Content
The user's password is updated, last_password_change is bumped, and every
active session is revoked. The caller must now log in with the new password.
Error responses
| Status | Code | When |
|---|---|---|
| 400 | invalid_input | Token missing, or new_password fails the length check. |
| 401 | authentication_required | Token doesn't match, already consumed, or expired. |
| 404 | not_found | User the token belongs to no longer exists. |
| 500 | internal_error | DB or hashing failure. |
Notes
- An audit entry (
auth.password_reset.consumed) is recorded. - All session-cache entries for the revoked sessions are invalidated so the middleware sees the revocation immediately on the next request.
- The reset is single-use; the row is marked
consumed_at = now()on success. - The
new_passwordis hashed with Argon2id before storage.