ok, this is what I figured out from the source code under gluon.tools.
I have a form with a nonSQLFORM input that allows the Manager to optionally force the user to reset the password. if that form is submitted correctly, under the form.process().accepted I have:
rv = request.vars
sent = ""
if (rv.active == "T") or ((xUser is not None) and (xUser.email <> uform.vars.email)):
sent = True
xUser.update_record(email=uform.vars.email, password=db.auth_user.password.validate('any_random_string')[0])
sent = sent and auth.email_reset_password(xUser)
if sent:
sent = " and Email Sent"
session.flash = "User Added/Updated"+sent
where xUser and uform is a db query and SQLFORM, respectively, for the user that the Manager is working on. the main idea is that xUser is update_record with the new email and an encrypted random string and then auth.email_reset_password will also update_record with the proper reset_password_key string and store all three fields in the database. it will then notify the user through an email the full link with the reset_password_key to the user and the user can then update their password under the link.
can also customize the subject and body of the email sent under db.py via:
auth.default_messages['reset_password_subject'] = "XYZ: Update your Changed Email/Password"
auth.default_messages['reset_password'] = "Login User/Email and/or Password have changed for your XYZ account. Click on the link: %(link)s to reset your password. Please choose a different password then used prior hand."
pretty smooth and I think it is working properly. anyone can offer further details. lucas