Password Reset


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 name Used as Default value
RESET_PASSWORD_SUBJECT Subject line Request to reset your Structr password
RESET_PASSWORD_SENDER_NAME Sender name Structr Mail Daemon
RESET_PASSWORD_SENDER_ADDRESS Sender address structr-mail-daemon@localhost
RESET_PASSWORD_TEXT_BODY Plaintext mail body Go to ${link} to reset your password.
RESET_PASSWORD_HTML_BODY HTML mail body <div>Click <a href='${link}'>here</a> to reset your password.</div>
RESET_PASSWORD_BASE_URL Used to build the link variable ${concat("http://",, ":", application.http.port)} (see structr.conf)
RESET_PASSWORD_CONFIRM_KEY_KEY key parameter name in the link variable. Allows the user to be logged in once without a password. key
RESET_PASSWORD_TARGET_PAGE_KEY target parameter name in the link variable. target
RESET_PASSWORD_TARGET_PAGE target parameter value in the link variable. Specifies the redirect page after successful login. /reset-password

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 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 resetPassword must to be allowed for public users
- PUTting to me must to be allowed for authenticated users

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 2017-05-04
Topics Structr 2.0