Introduction

Previously, you may have seen the use of project API keys in the article Integrating MODE to Your Existing Web Service. Here we will formally introduce the concept of project API keys and explain how you may use them in your MODE project.

Project API keys are authentication tokens provisioned by you for your project, so that you can use them in your programs or servers to access the MODE API. This gives you a great of deal of flexibility in creating your applications, since you can implement functions that do not require direct actions by your end users. For example, you may create a scheduler service that automatically sends commands to your devices at a given time every day.

Creating a Project API Key

To provision a project API key, go to the Settings screen of your project on the Developer Console. In the API Keys section, click the New button.

Enter a name for the API key then click Save. The entry for the newly created API key will appear.

Click on the entry to see the details of the API key, including the actual value of the key itself.

Your program or server can now use this authentication token in the Authorization HTTP header when making REST requests to the MODE API.

Permissions of a Project API Key

Using a project API key, your program will have the read permission on all devices, users and homes in your project. You may also notice that your newly created project API key was given some additional permissions by default. You should tailor the set of permissions to the specific needs of the program that will be using the API key.

Project API keys can be given one or more of the following additional permissions:

To modify the permissions of your project API key, click the edit icon.

Select the permissions you wish to give to the API key, then click Save.

Example Use Case: Managing User Subscriptions

If you are building a project on MODE and want to operate it as a subscription-based service, project API keys will be crucial to your implementation. In a subscription-based service, you may want to control a user's usage based on some conditions, such as payment. As the project owner, you can effectively limit a user's access to your service by deactiving the user's "home".

The "Deactivated" Flag

In the MODE API, the "home" data model has a deactivated field. If the value of this field is true:

In essence, a deactivated home is in some kind of read-only state. Access to the home is not completely cut off, so that your application may still be able to function in limited capacity. But the core functionalities of communicating with devices will be disabled.

Using Project API Key to Activate/Deactivate Homes

A likely scenario is that you may want to activate or deactivate a home based on some subscription status that you maintain separately. You may have a program or server that will carry out this action automatically for you.

Such a program should update the deactivated field of a home by making a PATCH request to the /homes/HOME_ID API endpoint. You should use a project API key for such requests. Most importantly, the API key you use must be given the "admin" permission, as described earlier.

Making Homes Deactivated by Default

A final consideration is how you want to handle new users and their newly created homes. If you want new users to activate their subscriptions before being able to use your service, you have the option to make all new homes to be deactivated by default. To enable this option, go to the Settings screen of your project on Developer Console. In the Advanced Options section, click the edit icon.

Select "Enabled" for "Make Homes Deactivated by Default", then click Save.

Now, new homes being created will have the deactivated flag set to true, until your subscription service updates them, using its "admin" project API key.