ForgotPassword API¶

Initiates the self-service password-reset flow for the user account(s) registered with the specified email address. The server looks up the account(s), generates a one-time reset token, and sends a password-reset email to the address. The token is then used with ChangePasswordUsingSecretText to set a new password.

No authentication ticket is required.

Endpoint¶

/srv.asmx/ForgotPassword

Methods¶

• GET /srv.asmx/ForgotPassword?emailAddress=...
• POST /srv.asmx/ForgotPassword (form data)
• SOAP Action: http://tempuri.org/ForgotPassword

Parameters¶

Note: This method does not require an authenticationTicket.

Response¶

Success Response¶

<root success="true" />

Error Response¶

<root success="false" error="Error message" />

Required Permissions¶

• No authentication required.
• The SMTP email service must be configured in the application settings for emails to be delivered.

Example¶

Request (GET)¶

GET /srv.asmx/ForgotPassword?emailAddress=jsmith@example.com HTTP/1.1
Host: server.example.com

Request (POST)¶

POST /srv.asmx/ForgotPassword HTTP/1.1
Content-Type: application/x-www-form-urlencoded

emailAddress=jsmith@example.com

Request (SOAP 1.1)¶

POST /srv.asmx HTTP/1.1
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://tempuri.org/ForgotPassword"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <ForgotPassword xmlns="http://tempuri.org/">
      <emailAddress>jsmith@example.com</emailAddress>
    </ForgotPassword>
  </soap:Body>
</soap:Envelope>

Password Reset Flow¶

Once the API returns success, the user receives an email containing a reset link in the form:

https://yourserver/resetpassword.aspx?username=jsmith&secretText=3f2a1b4c-5d6e-7f8a-9b0c-1d2e3f4a5b6c

The secretText value from this link (a GUID) is then passed to ChangePasswordUsingSecretText together with the username and the desired new password to complete the reset.

JavaScript¶

Every call answers XML with HTTP 200, success or not, so success is the thing to branch on and errorCode is the number to report. call below is used by the sample on every page.

async function call(action, params) {
  const response = await fetch(`/srv.asmx/${action}?${new URLSearchParams(params)}`);
  const root = new DOMParser()
    .parseFromString(await response.text(), 'text/xml')
    .documentElement;

  if (root.getAttribute('success') !== 'true') {
    throw new Error(`${root.getAttribute('errorCode')}: ${root.getAttribute('error')}`);
  }
  return root;
}

Mails a secret to the address on the account, which ChangePasswordUsingSecretText then takes.

await call('ForgotPassword', { emailAddress: 'jsmith@example.com' });

An address nobody has is refused rather than silently accepted, so do not show the error to the person typing it - it tells them whether the address has an account.

Notes¶

• Token expiry: The reset token is valid for 1 hour from the time the email is sent. After expiry it cannot be used.
• Multiple accounts per email: If more than one infoRouter user account is registered with the supplied email address, a separate reset email is sent for each account. The API returns success only after all emails have been dispatched.
• External-auth users: For accounts managed by an external authentication source (Windows/NTLM, LDAP, Active Directory), no reset link is generated. Instead, the user receives an informational email stating that their account is managed externally and they should contact their administrator.
• Email not found returns an error: Unlike some implementations that silently succeed to avoid email enumeration, this API returns a failure when no account is found for the given email address. Applications that wish to hide account existence should handle this error response without exposing it to the end user.
• Empty email rejected: Passing an empty or blank emailAddress returns an error immediately without any database lookup.
• Email format: The reset email is sent in the user's preferred format (HTML or plain text) and in the user's preferred language, both taken from the user's profile settings.
• Alternative: Use ForgotPasswordByUserName to initiate a reset by login name instead of email address.

Related APIs¶

• ForgotPasswordByUserName - Initiate password reset using the user's login name instead of email
• ChangePasswordUsingSecretText - Complete the reset by submitting the token received by email and a new password

Error Codes¶

The errorCode values this operation returns, checked against a running server: