Exploring Uses of Project API Keys

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.

Screenshot - Project Settings

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

Screenshot - Project API Key Entry

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

Screenshot - Project API Key Details

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.

Screenshot - Project API Key Permissions

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

  • Ability to handle administrative tasks such as initiating device provisioning or activating/deactivating homes.
  • Ability to send commands to devices.
  • Ability to send events to homes.
  • Ability to update home key-value stores and Device Data Proxy.
  • (For “Bring-Your-Own-Users” projects) Ability to create users and issue API keys for users.

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

Screenshot - Project API Key Edit

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

Screenshot - Project API Key Permissions Selection

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:

  • Users cannot send any commands to devices in the home.
  • Users cannot set or update key-value pairs in the Device Data Proxy of devices in the home.
  • Events emitted by devices in the home or other entities will not be propagated to any listeners.

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.

Screenshot - Project Advanced Options

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.