Forgot Username Flow

Registered users for your application may forget their username and lose the ability to log in to your app. Cloud CMS provides a "forgot username" flow that you can use to provide a way for end users to securely retrieve their username using their 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 "forgot username" convenience flow, you first need to have an Create new Application Keys 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 Forgot Username Flow

The "forgot username" flow works like this:

1. The web user tries to log in and realizes they don't know their username. They click a link that you provide to help them resolve this (usually something akin to "Forgot your username? Click here!").
2. The web user fills out a brief form where they provide their email address. They click submit.
3. Your application code calls Cloud CMS to create a "forgot username" request.
4. Your application code calls Cloud CMS to send the email for the "forgot username" request.
5. Your web site asks the user to check their email.
6. The user checks their email. The email contains a link back to a special page on your web site..

API Methods

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

Create a Forgot Username Request

To create a forgot username request, you need to make a call to Cloud CMS:

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

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": "As per your request, here is your username at Joe's Web Site.  You can use this username along with your password to <a href='http://website.com/login.html'>log in</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 forgot username request
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/requests/forgotusername/create",
    "data": {
        "principal": "joe@joe.com",
        "email": {
            "body": "As per your request, here is your username at Joe's Web Site.  You can use this username along with your password to <a href='http://website.com/login.html'>log in</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 forgot username request, you'll get back a JSON object containing the newly created forgot username ID (_doc). You will need to pass this ID to the next call in order to send the forgot username 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).

For more details on email definitions, see Send Email.

Send the Forgot Username Email

To send the forgot username email, you can simply do an empty POST to:

POST /pub/applications/{applicationId}/requests/forgotusername/{forgotUsernameId}/send

The forgot username 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. You may also wish to provide a link back to your application.

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

// the application
var applicationId = "GUID1";

// the forgot username request id
var requestId = "GUID2";

// send the forgot username email
$.ajax({
    "type": "POST",
    "dataType": "json",
    "processData": false,
    "url": "/pub/applications/" + applicationId + "/requests/forgotusername/" + requestId + "/send"
});