Request Password Reset

AUTHENTICATED BY X-API-Key, not by a bearer token. auth.APIKeyMiddleware REPLACES the usual chain on this route, so there is no user context, no RBAC check and no licence check — and the refusals are common.api_key_required / common.invalid_api_key rather than common.unauthorized / common.rbac_no_rec_access. An OPTIONS request skips the key check entirely. Request a password reset link for an email or phone credential. Subject to IP rate limiting (max attempts per 15 minutes; failed attempts tracked per hour). Always returns success when the credential is unknown to prevent enumeration.

curl -X POST "https://example.com/v1/users/request-password-reset" \  -H "Content-Type: application/json" \  -d '{    "credential_type": "email",    "credential_value": "string"  }'

{
  "status": 200,
  "message": "OK"
}

{
  "status": 400,
  "message": "Invalid user input",
  "code": "users_m.invalid_user_input",
  "class": "validation"
}

{
  "status": 401,
  "message": "common.api_key_required",
  "code": "common.api_key_required",
  "class": "business"
}

{
  "status": 403,
  "message": "common.invalid_api_key",
  "code": "common.invalid_api_key",
  "class": "business"
}

{
  "status": 429,
  "message": "Too many password reset attempts. Please try again in 842 seconds",
  "code": "users_m.password_reset_rate_limit_exceeded",
  "class": "temporary",
  "retryable": true
}

{
  "status": 500,
  "message": "Internal server error",
  "code": "common.server_error",
  "class": "business"
}

{
  "overall_status": "unhealthy",
  "message": "Service is shutting down",
  "timestamp": "2026-08-27T15:04:05Z"
}