Reset Password Flow

Registered users for your application may forget their password and lose the ability to log in to your app. Cloud CMS provides a "reset password" flow that you can use to provide a way for end users to securely reset their password using their username or registered email address.

On this page, we cover a public convenience method that applications can use to easily provide this functionality without having to through the most robust Cloud CMS object-level APIs. If you're interested in learning about the object-level APIs, take a look at:

The Custom Domain Name where new users will be created.
The Email Provider to be used to send emails to new users.

Let's now walk through the steps of using this convenience method.

Configure your Application Instance

To utilize the "reset password" convenience flow, you first need to have an Applications data store instantiated that will be used to store data for your mobile/web application. You can instantiate this through the Cloud CMS console or you can do so programmatically. Once you've done so, you will need to configure the application instance to have the following properties:

public.userDomainId - The ID of one of your platform's domains that should be used to store the new, registered users.
public.emailProviderId - The ID of one of your platform's email providers that should be used to send emails.

Sample configuration

The following JSON can be appended into your Application JSON (which you can edit within the Cloud CMS console). Or you can edit your application and enter these values via a form.

{
    "public": {
        "userDomainId": "primary", // either "primary" or a domain ID
        "emailProviderId": "{Email Provider GUID}"
    }
}

The Reset Password Flow

The "reset password" flow works like this:

The web user tries to log in and realizes their password is incorrect, invalid or otherwise isn't working. They click a link that you provide to help them resolve this (usually something akin to "Forgot your password? Click here!").
The web user fills out a brief form where they provide their email address or username. They click submit.
Your application code calls Cloud CMS to create a "reset password" request.
Your application code calls Cloud CMS to send the email for the "forgot username" request.
Your web site informs the user that an email was sent and that they should click the link contained in the email to verify their email address and reset their password.
The user checks their email and clicks the link. The user's browser is taken to a password reset page on your web site. This page receives a "hash" request parameter which is used to commit the reset password (below).
The web site user fills in any additional information they need to supply. They click submit.
Your application code collects the new password, validates it and then commits the reset password request by calling to Cloud CMS.
Cloud CMS updates the user's password.

API Methods

Below we cover step-by-step how to use the API methods to complete a "reset password" flow. For technical details on using the public application services API, please see:
Public Application Services API

Create a Reset Password Request

To create a reset password request, you need to make a call to Cloud CMS:

POST /pub/applications/{applicationId}/requests/resetpassword

You need to specify the ID of your Application instance in the path to the method.

The body of your POST should contain two fields that contain the username and email definition. These are contained in the principal and email fields, respectively. Like this:

{
    "principal": "joe@joe.com",
    "email": {
        "body": "<a href='http://website.com/password-reset.html?hash=${hash}'>Click me to reset your password</a>",
        "from": "webmaster@website.com"
    }
}

Here is an example of using some straightforward jQuery to create the request:

// the application
var applicationId = "GUID1";

// create the reset password request
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/requests/resetpassword/create",
    "data": {
        "principal": "joe@joe.com",
        "email": {
            "body": "<a href='http://website.com/password-reset.html?hash=${hash}'>Click me to reset your password</a>",
            "from": "webmaster@website.com"
        }
    }
});

And here is a list of everything that can be passed in when defining the request:

{
    "principal": "", // either the email, id or username of a principal
    "email": {
        // email properties (see email request API)
    }
}

When you create a reset password request, you'll get back a JSON object containing the newly created reset password ID (_doc). You will need to pass this ID to the next call in order to send the reset password request email to the end user.

As part of creating the request, you need to provide an email definition that describes the email that is being sent out. In defining the email body, you have access to a model which provides variables that you may choose to use within your template. In particular, the user variable is available which provides all properties about the user including their user name (provided as user.name).

There is also a hash variable which should be used to build the link back to your web site. The hash is used by the next step to commit the password reset.

For more details on email definitions, see Send Email.

Send the Reset Password Email

To send the reset password email, you can simply do an empty POST to:

POST /pub/applications/{applicationId}/requests/resetpassword/{resetPasswordId}/send

The reset password email will be sent and it will contain the body and properties as defined in the email templates block within your request configuration.

Once the email is sent, the end user will receive an email that is formatted according to your template. Your template can use the user model variable to provide the user.name username to the end user.

This email must contain a link that they can follow to continue the reset password flow. This link must connect to your web site and the link should also pass along a request parameter (or a hash link) that contains the ${hash} for the reset password request. This hash is generated by the reset password flow and will only be made available to the email recipient. When the end user clicks on the link, the hash is passed over to your web site.

Your web site then uses this hash to confirm the password reset. This is described in the next step.

Here is an example of using some straightforward jQuery to send the email:

// the application
var applicationId = "GUID1";

// the reset password request id
var resetPasswordId = "GUID2";

// send the registration confirmation email
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/requests/resetpassword/" + resetPasswordId + "/send"
});

Commit the Reset Password Request

To complete the password reset, you simply need to call over to Cloud CMS and pass along the new password for the user. This is passed along in the POST payload, as shown here:

{
    "password": "" // the password
}

Here is an example of using some straightforward jQuery to commit the password reset:

// the application
var applicationId = "GUID1";

// the reset password request hash
var hash = "HASH";

// confirm the registration (and send welcome email)
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/requests/resetpassword/" + hash + "/commit",
    "data": {
        "password": "password1"
    }
});

When the method completes, the user's password will be updated.