POST /v1/auth/password/forgot
Send a password reset link to a user's email. Always returns 204 to defeat account enumeration.
::: tip Auth Required: none. :::
Request
POST /v1/auth/password/forgot
| Header | Required | Notes |
|---|---|---|
Content-Type: application/json | yes | — |
Body
{ "email": "alice@example.com" }
Response
204 No Content
Always 204. The response is identical for:
- Registered active accounts (link sent)
- Registered disabled / deleted accounts (silently dropped)
- Unknown emails (silently dropped)
- Malformed email input (silently dropped)
Error responses
| Status | Code | When |
|---|---|---|
| 500 | internal_error | Database or email transport failure. |
Notes
- Tokens are 32-byte URL-safe base64, hashed as SHA-256 in storage.
- Token TTL: 1 hour.
- The link in the email points to
{public_base_url}/reset-password?token=...— your frontend handles that path and submits to/v1/auth/password/reset. - Any prior outstanding reset tokens are deleted before the new one is minted.
- Highly time-sensitive deployments may want to add a random delay in front of this endpoint to defeat timing-based enumeration.