Introduction

Each HTTP request from a device to the MODE API must contain an API key in the Authorization HTTP header.

Getting the Device API Key

You can locate the API key of your device in the MODE Developer Console. On the Developer Console, navigate to My Projects > Select a Project > Devices > Select a Device Class > Instances > Select a Device Instance. Here, you will see the settings of the device intance including the Device API Key.

Verification of Device API Key

To verify that your device API key is working, run the following command (replace _YOUR_API_KEY_ with the actual API key):

$ curl -i -N -H "Authorization: ModeCloud _YOUR_API_KEY_" https://api.tinkermode.com/auth

The raw HTTP request is as follows:

GET /auth HTTP/1.1
Host: api.tinkermode.com
Authorization: ModeCloud _YOUR_API_KEY_

If you succeed, you will see a response similar to the following:

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: Tue, 25 Aug 2015 21:22:49 GMT

{"deviceId":11,"projectId":11,"type":"device"}

The actual JSON object returned may vary depending on your device configuration. If the API key used was incorrect, you could see the following response:

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: Tue, 25 Aug 2015 21:22:49 GMT

{"type":"nobody"}

Because you passed the wrong API key, the MODE cloud did not recognize the caller as a device. If you want to see the whole HTTP transaction under the hood, you can run the cURL command with the -v option.

Device API Keys Storage Option

While it is convenient to use MODE as the central repository for all your devices' API keys, for added security, you may choose to store the keys separately on your own instead. To stop MODE from storing your project's device API keys, go to Settings of your project on the Developer Console. Click Turn off Storage in the Device Keys Storage section:

Selecting this option has two effects:

1. All existing device keys will be purged from MODE's database.
2. Device keys generated from now on will not be stored in MODE's database.

Also note that this option is irreversible. So before you selecting this option, make sure you back up all your existing device keys first. To do so, go to the console for each of your Device Classes, and click Export in the Device List section:

All the metadata of your device instances for that Device Class, including the API keys, will be exported as an JSON file.

Once you have opted out of storing device API keys in MODE, each time you create a new device instance, you must immediately save the generated API key in a secure place. You will not be to retrieve this key from MODE again.