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 HTTP request header. In this API reference, if Authorization header is needed
for an endpoint, there will be further details about which particular types of
client token are expected.
Authorization HTTP request header should be in the following format:
Authorization: ModeCloud <AUTH_CODE>
<AUTH_CODE> is an authentication token.
How the authentication token can be obtained depends on the nature of the API client, as explained below:
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
Once the user is authenticated, a user session is created and an API key associated
with the user session is returned. You may use this API key as the
subsequent API requests. For reference, if you sign on as a user to the "App Simulator",
the user session API is revealed when you click Show API Key.
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.
If you are using On-demand Device Provisioning, this key is returned in the API call that adds a device to a home.
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.
Content Type and Content Length Headers
If an API request contains a request body, it must also contain
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