Introduction

In most cases, you are using MODE as the core cloud service for your IoT system. Your devices and mobile apps communicate directly with the MODE cloud. In particular, MODE has a built-in user account system that handles registration and login requests from your end users. There is no need for you to set up your own user database.

However, if you already have an existing web service, with its own user account system, you may want to use MODE simply as a backend system for managing device connectivity, ownership and access. MODE supports this use case and you can easily set up a MODE project to work seamlessly with your web service.

System Architecture

The following diagram illustrates how your server can be positioned in relation to MODE and other components of your system.

Your users, with either a mobile or web app, communicate with your web service directly. Your server handles user registration, verification, login, etc., and maintains a user database.

On the other hand, your devices commuincate with the MODE cloud directly, just like in all other use cases.

When a user wants to take an action involving MODE, she would make a call to your web service. Your server would authenticate the user request, using an authentication scheme you have implemented for your service. Then on behalf of the user, your server would make the appropriate REST request to the MODE API to carry out the action.

Project Setup

To build such a system, you need to create a MODE project that gives your server special authority to handle user accounts. In particular, when you create your project, you will be prompted to pick a User Accounts option. You should pick the option that says "You have your own user account system."

Projects created this way are referred to as "Bring-Your-Own-Users", or BYOU, projects. Please note that this option cannot be changed once the project has been created. If you make a mistake, you can delete the project and start a new one.

In the newly created project, go to the Settings screen. In the API Keys section, click the New button to create a new project API key.

Click the entry for your newly created API key to reveal the details of the key. Click the edit icon at the top right corner to modify the Permissions attribute. Make sure the Can Handle BYOU option is selected:

Click Save. Take note of the actual token assigned to this key. You will need this API key for the operations described next.

For more information on project API keys, see this article.

Linking Your Users to MODE

Although your web service has its own user database, in order to use MODE to manage device ownership and access control, you need to establish a link to a user entry in MODE for each of your active users.

For instance, a new user has just registered with your service. After creating an account entry for that user in your database, your server should set this user up in MODE as well, by making a POST request to the /users endpoint of the MODE API. This request must use the project API key you created earlier in the Authorization HTTP header, as shown in the following cURL example (replace PROJECT_API_KEY and PROJECT_ID with the actual API key token and project ID):

$ curl -i -N -H "Authorization: ModeCloud PROJECT_API_KEY" -H "Content-Type: application/json" -d "{\"projectId\": PROJECT_ID}" 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":true,"name":"","creationTime":"2015-09-25T23:46:06.541Z"}

In the above example, a MODE user entry with the ID 77 is created. Now, you should acquire an API key for this user by making a POST request to the /auth/user endpoint of the MODE API. Again, make sure you use the project API key in the Authorization header of the request. For example (replacing PROJECT_ID with the actual project ID):

$ curl -i -N -H "Authorization: ModeCloud PROJECT_API_KEY" -d "projectId=PROJECT_ID&userId=77" 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}

You should store both the MODE-assigned user ID and API key in your user database, along with the user's other account information. This user in the example is now linked to user 77 in MODE. From now on, whenever your server needs to make a MODE API call on behalf of this user, it should look up the API key from your database and use it in the Authorization header of the request.

General Use of MODE API

Once your user has been set up in the steps described above, the use of the MODE API is very much identical to that of a regular MODE project. For example, using the user's API key, you can make API calls to create a home, add devices to a home, issue commands to devices, etc.

One exception is how members are added to a home. You can add someone to a home only if you know the MODE user ID of that person. That means when a user wants to add a member to her home, you may implement the following steps:

Depending on your specific application, you may implement this flow differenty. For example, you may simply send out email to the invitee and wait for her confirmation before actually carrying out the database and API operations.

Events Propagation and Handling

Since your users will be communicating with your web service, rather than with the MODE cloud directly, special considerations are needed in dealing with events propagation and handling.

One solution is to add webhooks to your project, using a Webhooks Smart Module. This Smart Module should be configured with an Event Webhook that points to a special URL in your web service. Whenever a device emits an event, this URL will be called. The handler of this URL will then interpret and handle the event according to the context of your web service. For example, you may update your database, or send a push notification to a user.

For more information on setting up a Webhooks Smart Module, see this tutorial.