Password reset
Requesting a reset link and completing the reset — the two writes that need no session.
Password reset is the only write path in the whole auth surface that does not require a session, because "I forgot my password" presupposes "I cannot get in". Precisely for that reason it has to carry all of its own protection: IP rate limits, per-address throttling, single-use short-lived tokens, and revoking every session at the end.
Endpoints
| Method | Path | Purpose |
|---|---|---|
POST | /v1/auth/password-reset | Request a reset link |
POST | /v1/auth/password-reset/complete | Complete the reset with the token |
Neither accepts a Bearer token, and neither requires Turnstile — the human check is there to stop bulk registration and credential-stuffing scripts, and here IP and per-address throttling already do that job.
Requesting a reset
| Parameter | Type | Required | Notes |
|---|---|---|---|
email | string | ✅ | Address that should receive the reset mail |
{ "success": true, "message": "If this address is registered, a reset link has been sent" }The response must be identical
Whether or not the address is registered, the response is the same. Delivery failures are swallowed too: turning a failure into a 5xx would let an attacker infer registration status from "did it error". The failure is still recorded in logs and alerts — it just does not surface in the response.
Only accounts with a password credential receive mail. Accounts without one (passkey-only or third-party-only) go through account recovery instead.
Completing the reset
| Parameter | Type | Required | Notes |
|---|---|---|---|
token | string | ✅ | Single-use token from the email |
new_password | string | ✅ | New password, 8–128 chars |
{ "success": true, "message": "Password updated; 3 session(s) signed out" }The token is single-use and short-lived, and dies on first use. After a successful reset every session of the account is revoked — the old password may already have been in someone else's hands, and keeping sessions alive leaves the intruder inside the house.
Related
- Changing the password while signed in: Password credential
- FAQ: Passwords and recovery