Introduction

When you build your project on MODE, you can leverage the built-in user account system to register and authenticate your end users. Two options are available for your project:

When you first create your project, you will be prompted to select one of these options. You should pick the one that best suits the use cases you are targeting.

Note that your selection cannot be changed once the project has been created. If you make a mistake in your choice, you can delete the project and start a new one.

You can also opt out of using the built-in user account system completely and instead integrate your project with a separate account system. For details, see the article on Integrating MODE to Your Existing Web Service.

This guide will focus on describing how the built-in account system works in the "phone number option" and the "email address option".

The Phone Number Option

If your end users will be using a mobile app as the primary way to interact with your project, you can consider picking this option for your user account system. Your users will register their accounts using their phone numbers. To log in, a user will request an authentication code to be sent to their phone via SMS. She can then use the code to authenticate herself. No password is required.

Specifically, your app should implement the following user flows:

User Registration

To register a new user, your app should prompt her to input her name and mobile phone number. Your app can then create a new user in the project by making a POST request to the /users endpoint of the MODE API. The request body must contain the name and phoneNumber fields, as shown in the cURL example below (replace PROJECT_ID with the actual ID of your project):

$ curl -i -H "Content-Type: application/json" -d "{\"projectId\": PROJECTID, \"name\": \"Jen Law\", \"phoneNumber\": \"+16505558888\"}" https://api.tinkermode.com/users

If the request is successful, the response should look similar to the following:

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Location: /users/77
Date: Fri, 25 Sep 2015 23:46:06 GMT
Content-Length: 118

{"id": 77, "projectId": PROJECT_ID, "verified": false, "name": "Jen Law", "phoneNumber": "+6505558888", creationTime": "2015-09-25T23:46:06.541Z"}

An SMS text containing a one-time authentication code will be sent to the user's phone automatically. Your app should prompt the user to enter this code to authenticate herself and log in, as demonstrated in the next section.

User Authentication

To authenticate a user, your app should make a POST request to the /auth/user endpoint of the MODE API. The request body must contain the user's phone number and the authentication code sent via SMS, as shown below (replacing PROJECT_ID and APP_ID with the actual project and app IDs):

$ curl -i -d "projectId=PROJECT_ID&appId=APP_ID&phoneNumber=%2B16505558888&code=999999" https://api.tinkermode.com/auth/user

The response should look similar to the following, where API_KEY would be the API key assigned to the user:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Date: Sat, 26 Sep 2015 00:31:00 GMT
Content-Length: 104

{"token": "API_KEY", "userId": 77}

Your app should store the API key as well as the user ID. The API key is tied to a user session and should be used in the Authorization HTTP header in all subsequent calls to the MODE API.

As mentioned earlier, the authentication code is sent to the user automatically right after registration. For an existing user, your app can initiate the authentication process by requesting a new code to be sent to the user. This is done by a POST request to the /auth/user/sms endpoint, as shown below:

$ curl -i -d "projectId=PROJECT_ID&phoneNumber=%2B16505558888" https://api.tinkermode.com/auth/user/sms

The Email Address Option

This option provides a user experience that is typical of most web services. Each of your users will enter her email address and select a password when she registers her account. She will need to verify the email address by clicking a link in a verification email sent to her. To log in, she simply uses her password.

Your app is expected to handle the following user flows:

User Registration

To register a new user, your app should prompt her to input her name, email address and a password. Your app can then create a new user in the project by making a POST request to the /users endpoint of the MODE API. The request body must contain the name, email and password fields, as shown in the cURL example below (replace PROJECT_ID with the actual ID of your project):

$ curl -i -H "Content-Type: application/json" -d "{\"projectId\": PROJECTID, \"name\": \"Jen Law\", \"email\": \"jlaw@example.com\", \"password\": \"xxxxxxxxx\"}" https://api.tinkermode.com/users

If the request is successful, the response should look similar to the following:

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Location: /users/77
Date: Fri, 25 Sep 2015 23:46:06 GMT
Content-Length: 118

{"id": 77, "projectId": PROJECT_ID, "verified": false, "name": "Jen Law", "email": "jlaw@example.com", creationTime": "2015-09-25T23:46:06.541Z"}

An email containing a verification link will be sent to the user. The user can log in to her account only after she has clicked the verification link.

About Password Security: As in all systems that depend on password authentication, your app should perform tests on passwords entered by users and reject those that are too short or easily guessable.

Resending Verification Email

If for whatever reason the user has lost the verification email, you can request it to be resent by making a POST request to the /auth/user/emailVerification/start endpoint.

User Authentication

To authenticate a user, your app should make a POST request to the /auth/user endpoint of the MODE API. The request body must contain the user's email address and a password, as shown below (replacing PROJECT_ID and APP_ID with the actual project and app IDs):

$ curl -i -d "projectId=PROJECT_ID&appId=APP_ID&email=jlaw@example.com&password=xxxxxxxxx" https://api.tinkermode.com/auth/user

If the password is correct, the response should look similar to the following, where API_KEY would be the API key assigned to the user:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: false
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: X-Xsrf-Guard
Content-Type: application/json; charset=utf-8
Date: Sat, 26 Sep 2015 00:31:00 GMT
Content-Length: 104

{"token": "API_KEY", "userId": 77}

Your app should store the API key as well as the user ID. The API key is tied to a user session and should be used in the Authorization HTTP header in all subsequent calls to the MODE API.

Resetting Password

If a user has forgotten her password, your app can request a password reset email to be sent to her. This is done by making a POST request to the /auth/user/passwordReset/start endpoint. The user will receive an email containing a password reset link. When she clicks the link, she will land on a web page where she can save her new password.

Logging Out

When a user logs out of your app, it simply means your app should reset its state and discard the API key assigned to the user session. However, it is good practice to explicitly terminate the user session before discarding the key. This is done by making a DELETE request to the /userSession endpoint of the MODE API.

Customizing SMS and Email Messages

As you can see, handling of user accounts and authentication involves communication with your users either via SMS texts or emails. MODE allows you to customize the content of these messages so that you can provide your users with the best possible experience.

If your project is using phone number-based accounts, you can modify the template used for the SMS texts sent to users during authentication. To do so, go to Settings of your project on the Developer Console. Locate the section for User Authentication Message:

Click the edit icon at the top right corner to change the content of the template. Make sure your template contains the variable {{"{{CODE"}}}} which will be automatically substituted with an authentication code when the message is sent.

If your project is using email address-based accounts, you can modify the templates used for the various email messages sent to users for account verification, password reset, etc. Simply go to Settings of your project on the Developer Console and locate the Email Templates section:

Select one of the entries in the section to view the content of the template. For example, if you select User Verification, you will see the template for the message sent when a new user registers.

To change the content of the template, click the edit icon in the top right corner of the Message section. The template can reference variables such as {{"{{USER_NAME"}}}} and {{"{{USER_EMAIL"}}}}, which will be substituted with the appropriate values when the email is sent.

Both the templates for user verification and password reset must contain links the recipients can click to complete the relevant action. By default, the templates contain links to web pages hosted by MODE. To fully customize your project's user experience, you should replace these links with URLs that point to your own web pages or apps. (But make sure you include the necessary token parameter in your URLs.) Review the source code of the web pages referenced by the default templates to see how you can implement your own version.