Skip to main content

Reset Password

POST 
/auth/reset-password

Consume a reset link and rewrite the user's password (SCRIFT-82).

On success, the response is a static 200 message and the client must redirect to /auth/login - we do not mint tokens here by design. Every refresh token for the user is revoked inside the same transaction as the password update (NIST SP 800-63B §5.1.1.2), so any previously-issued session is dead the moment the response returns.

Errors (via exception_handlers):

  • 400 reset_token_invalid - hash not found
  • 400 reset_token_expired - past 1h expires_at
  • 400 reset_token_already_used - second click, or race-loser in the guarded mark_used UPDATE
  • 422 weak_password - fails :meth:AuthService.validate_password_strength
  • 429 - address-keyed budget exhausted

Rate limit: 10/hour per client address. The token is the real control here - 256 bits of randomness is not brute-forced - and this limit does not pretend otherwise. It is defence in depth: a real user submits once, maybe twice, so the cap costs them nothing, while unauthenticated probing of token validity stops being free. "Infeasible" is a claim about today's arithmetic, and controls should not rest on a single one.

⚠ POST only, deliberately. Enterprise and university mail gateways prefetch links. If a GET could consume a token, those users' resets would fail before they ever clicked, and the failure would look random. Nothing in this flow consumes a token except the user's own submission.

Request​

Responses​

Successful Response