Introduction


Requests to the MODE API are usually made by one of the following entities: a user (by way of a mobile or web app), a device, or an authorized external program/service.

Authorization Header


An API client can identify itself by using the Authorization HTTP request header, which contains an authentication token. Some, but not all, API requests will require this Authorization HTTP request header. In each endpoint description, there is a section for "Authorization" that will describe the identification needed.

The Authorization HTTP request header should be in the following format:

Authorization: ModeCloud <AUTH_CODE>

where <AUTH_CODE> is an authentication token.

How the authentication token can be obtained depends on the nature of the API client, as explained below. Here are the ways to obtain this token:

Users

The AUTH_CODE is obtained through requests to the Client Authentication endpoints. Depending on project settings, user authentication may involve round-trip verification by an SMS message, direct password input, or special server-to-server API calls.

Once the user is authenticated, the User API Key is used as the AUTH_CODE. For refence, the User API Key can be found on the Developer Console under Apps > App Simulator (Launch Simulator) > Log In > User API Key.

Screenshot - Console User API Key

Devices

The AUTH_CODE is the API Key assigned to a device instance when it was provisioned. If the device was pre-provisioned, you can retrieve this key from the Developer Console under Devices > Select a Device Class > Select a Device Instance > Device Details > API Key.

Screenshot - Console Device API Key

If you are using On-demand Device Provisioning, this key is returned in the API call that adds a device to a home.

Other Clients

Project API Keys can be created for external programs or services that integrate with the MODE platform. For example, you may have a scheduler service that sends commands to your devices periodically. Or, if you have your own user account system, your server will need to make backend API calls to MODE during user registration and login.

For these API clients, you can provision Project API Keys in your project's Settings screen on the Developer Console. You can also control what additional permissions a Project Key can have besides basic API access.

Screenshot - Console Project API Key

Content Type and Content Length Header


If an API request contains a request body, it must also contain Content-Type and Content-Length headers. Depending on the API resource/endpoint, the request body is expected to be either in JSON (application/json) or as a web form (application/x-www-form-urlencoded).