Request a password-reset email
POST/user/password-reset
Request a time-limited password-reset link for an account identified by either username or email, not both. This is public account recovery, not an administrative password operation.
Privacy and delivery
- Return the same
202response for known, unknown, ambiguous and ineligible accounts, including account-specific delivery failures. - Do not expose account IDs, tokens, delivery status or a result lookup URL. Use a common response path and deferred delivery to avoid account-dependent response timing.
- Log delivery failures privately, regardless of the site's username-disclosure setting.
- Reuse Moodle's existing recovery eligibility, token expiry, single-use and redemption rules. The email links to Moodle's existing password-reset page.
- Requesting a link does not change the password or force a logout. Ambiguous email matches must not select an arbitrary account.
Abuse and retries
- Apply account-independent request throttling and per-identifier delivery limits.
- Apply the same identifier-limit behaviour whether or not an account exists. Suppress repeated emails without changing the generic acceptance response.
- Request-level throttling may return
429withRetry-After. Service-wide failures may return a generic503; account-specific outcomes remain private.
Permissions
No API authentication or OAuth scope is required.
Request
Responses
- 202
- 400
- 422
- 429
- 503
Request accepted for consideration. This does not confirm account existence, eligibility or email delivery. No Location or delivery receipt is returned.
Response Headers
Prevent storage of password-management and recovery responses.
Bad Request
Well-formed input failed field validation: missing required, unknown or read-only fields, invalid values, policy failures or incompatible options. Permission or locked-field failures use 403; uniqueness conflicts use 409. Public recovery errors describe input only, never account existence, eligibility or delivery outcomes. Passwords and recovery tokens must not appear in errors.
Request-level rate limit exceeded, independently of whether the submitted account exists.
Response Headers
Seconds before another request should be attempted.
Recovery is temporarily unavailable for all callers. Never use this response to reveal an account-specific delivery failure.