To allow users to regain access to their account when they forgot their password we need to enable them to reset their password.

Note: The Mail Configuration has to be done for password retrieval mails to be sent.


The password reset mail is constructed from multiple MailTemplate (see MailTemplate) objects.

MailTemplate nameUsed asDefault value
RESET_PASSWORD_SUBJECTSubject lineRequest to reset your Structr password
RESET_PASSWORD_SENDER_NAMESender nameStructr Mail Daemon
RESET_PASSWORD_SENDER_ADDRESSSender addressstructr-mail-daemon@localhost
RESET_PASSWORD_TEXT_BODYPlaintext mail bodyGo to ${link} to reset your password.
RESET_PASSWORD_HTML_BODYHTML mail body<div>Click <a href='${link}'>here</a> to reset your password.</div>
RESET_PASSWORD_BASE_URLUsed to build the link variable${concat("http://",, ":", application.http.port)} (see structr.conf)
RESET_PASSWORD_CONFIRM_KEY_KEYkey parameter name in the link variable. Allows the user to be logged in once without a password.key
RESET_PASSWORD_TARGET_PAGE_KEYtarget parameter name in the link
RESET_PASSWORD_TARGET_PAGEtarget parameter value in the link variable. Specifies the redirect page after successful login./reset-password

Technical Note: The visibility flags of these mail templates is irrelevant as the password reset mail is created as a privileged user.

Example link variable:<PASSWORD-RESET-KEY>&target=/reset-password

Note: Since all necessary templates have defaults none of them is strictly necessary but in order to deliver a better user experience at least the first three are recommended.

Requesting a password reset

The process is multi-step:

  1. The user needs to request a “Reset password” mail by POSTing his email address to /structr/rest/reset-password as follows

        eMail: ""
  2. If the email address exists in the user database the password reset mail (constructed according to the above definitions) will be sent to the specified address

  3. Upon clicking the link the user will be logged in and redirected to the specified target page where he can change his password

  4. The user can now change his password by PUTting a new password to /structr/rest/me (see Static Resources)

        password: "newSuperSecurePassword"

Note: The key JsonRestServlet.user.autologin in structr.conf needs to be set to true in order for the user to be auto-logged in.

Note: The authentication key is valid once and deleted after usage. The user could also decide to use the application without changing his password as he is now logged in.

Note: For step 1 and 4 to work the correct Resource Access Grants must be configured:
- POSTing to resetPassword must to be allowed for public users (Grant Signature: _resetPassword)
- PUTting to me must to be allowed for authenticated users (Grant Signature: User)

Note: Steps 1 and 4 are usually done using JavaScript / jQuery / AJAX and are left for the reader to implement.


About this article
Last change 2018-12-04
Topics Structr 2.0