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.
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:
- 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.
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:
- 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.
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.