How do I implement, customize, and troubleshoot password reset in Piano Identity Management?

1. Trigger the password reset screen

HTML link inside a Identity Management template

<a showScreen="restore" class="link"><t>Request a password reset link</t></a>

JavaScript (from anywhere on your site)

tp.pianoId.show({
  disableSignUp: true,
  displayMode: 'modal',
  screen: 'restore'
});

displayMode: 'modal' is the default and may be omitted.

Reset password from My Account

Wrap the JS in a <custom-script> (not <script> - the standard tag may be filtered):

<button onclick="showResetPasswordModal()">Reset my password</button>
<custom-script>
function showResetPasswordModal() {
  tp = window.tp || [];
  tp.push(['init', function() {
    tp.pianoId.show({
      disableSignUp: true,
      screen: 'restore'
    });
  }]);
}
</custom-script>

Add a "Back to login" button on the reset page

<p class="final">
  <a showScreen="login" class="link"><t>Back to login</t></a>
</p>

2. The reset landing page (Identity Management Password Reset JavaScript)

When a user clicks the link in the reset email, they land on a page with a reset_token query parameter. Add this JavaScript to that landing page so the Identity Management new password page template appears automatically:

tp = window.tp || [];
tp.push(['init', function() {
  // Password can be reset only if user is anonymous
  if (!tp.user.isUserValid()) {
    // If URL has reset_token parameter
    var tokenMatch = location.search.match(/reset_token=([A-Za-z0-9]+)/);
    if (tokenMatch) {
      // Get value of the token
      var token = tokenMatch[1];
      // Present password reset form with the found token
      tp.pianoId.show({
        'resetPasswordToken': token,
        loggedIn: function () {
          // Once user logs in - refresh the page
          location.reload();
        }
      });
    }
  }
}]);

The script checks the user is anonymous (only anonymous users can reset), reads reset_token from the URL, calls tp.pianoId.show({ resetPasswordToken: token }), and reloads the page on successful login.

3. Customize the password reset email

Email variables

Configure the email in Manage → Email Manager → Identity Management password reset request. Supported variables:

Construct the reset link in the template as:

<a href="{{reset_password_url}}/?reset_token={{reset_token}}">Reset Password</a>

Once the template uses this format, the url parameter you pass to the publisher/reset/password API endpoint can override the full_reset_link otherwise configured on the email.

4. Customize the reset error message

In the Identity Management new password page template, locate:

<span showIfPasswordInvalidBy="PASSWORD_MIN_LENGTH" class="error-message">
  <t>Minimum number of characters required for user password.</t>
</span>

Update the <t> text, e.g.:

<span showIfPasswordInvalidBy="PASSWORD_MIN_LENGTH" class="error-message">
  <t>You need at least 8 characters for a user password.</t>
</span>

5. Sandbox setup

In Sandbox, password reset emails only generate if an active Master email layout is configured. The default "no template" state suppresses them.

To enable:

1. Open Email Manager in the Piano Dashboard.

2. Duplicate the Master email layout, name the copy, save, and set as active.

3. Ensure Identity Management password reset request is toggled ON.

4. Trigger a reset via "Forgot password?" or Dashboard → User → Reset password.

5. Refresh the user profile and check the Emails tab to see the message.

Note: Sandbox emails appear in the log but are not delivered to real mailboxes. Scheduled emails do not run in Sandbox. Confirm the user exists in the correct Sandbox AID.

6. Troubleshooting

Reset emails not generating at all

• Confirm the master email layout is set to an active, non-default template (see Section 5).

• Confirm Identity Management password reset request is enabled in Email Manager.

Microsoft / Outlook / Hotmail / MSN delivery rejections

Microsoft mailboxes frequently reject Piano password reset emails because Mandrill rewrites the link for open tracking - the visible href and the rewritten href differ, which trips spam filters and may produce scam warnings.

To resolve:

1. Disable Mandrill link rewriting for the reset link: add an explicit href attribute to the link in your Identity Management password reset requests template. Mandrill leaves links with explicit href attributes alone. After this, the link reaches mailboxes intact, with no scam warning.

2. Check bounce messages. "Transient/General" bounces indicate temporary recipient-side issues.

3. Verify DNS, SPF, DKIM to maintain sending reputation.

4. Send test emails to hotmail.com / outlook.com / msn.com after each change.

5. Contact the provider if blocks persist - the issue may be in their block list or filtering policy.

Custom reset_password_url not honored

• Confirm the email template uses {{reset_password_url}} + {{reset_token}} (Section 3) so the URL passed to publisher/reset/password can take effect.

• Confirm the latest backend updates are applied.

7. Implementation checklist

1. Enable Identity Management password reset request in Email Manager.

2. Ensure an active Master email layout exists (especially in Sandbox).

3. Populate the email template with {{reset_password_url}}/?reset_token={{reset_token}}.

4. Add the landing-page JavaScript from Section 2 to your reset landing page.

5. Confirm the reset trigger HTML (<a showScreen="restore">) or JS (tp.pianoId.show({ screen:'restore' })) is in your login screens / My Account.

6. (Optional) Add a "Back to login" link to the restore template.

7. (Optional) Customize the error message text in Identity Management new password page.

8. Test in Sandbox, then promote to Production.

Last updated: July 03, 2026