API Access

The EmbedThis Ioto API is a REST API to allow you to interact with the backend Ioto cloud service.

The Ioto API provides calls to:

• Claim and release devices
• Access device database data
• Create and access metric data
• Provision devices with certificates and credentials
• Manage devices
• Invoke automated actions

The Ioto API can be used from browser-based UI apps or from utility service commands running in the cloud or on-prem.

Authentication

Requests to the Ioto service are authenticated by checking an authentication token included with the request. Ioto provides two different authentication methods for two use cases:

Authentication Method	Source	Description
CloudAPI Token	Utility	An admin service running in the cloud or on-premises
Login Access Token	Browser	A logged in user from a web browser app

For logged in users, Ioto offers Login Access Tokens which are granted when a user logs into the service. For utility service commands, Ioto offers CloudAPI Tokens which provide administrative access to the device cloud and the resources in the cloud.

An authentication token must be included in the HTTP headers for Ioto API requests.

API Endpoint

The Ioto API endpoint is unique per device cloud. You can see the API endpoint in the Builder Cloud/Edit panel under the API Access section.

The Endpoint is of the form: SITE/PATH

For example:

https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/user/find

HTTP Methods

All HTTP API requests use the POST method for consistency and simplicity.

HTTP Request Paths

When using Authentication tokens, the request URLs are modified to include a "/tok" URL prefix before the URL path.

For example:

https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/tok/user/find

HTTP Headers

To authorize your request, include the authentication token as an Authentication HTTP header with your request. All API requests use a HTTP Content-Type of application/json for both requests and responses.

If using login access tokens, you must also include an Origin header that is set to the domain name for your device app.

For example:

Authorization: 1234567990X0C3B0ABF3CF81DZ....
Content-Type: application/json

Request Responses

Successful Responses

Successful requests will return a HTTP status code of 200 and a response body containing a JSON object with the following properties:

• data - The response data

If the response contains an array of data, the response will also contain the following properties:

• next - The next page of results
• prev - The previous page of results
• paged - Set to true if the response is paged

Errors

REST HTTP calls will return a HTTP status code of 200 for success, 403 for authentication errors, 400 for bad requests, and 500 for service errors. When a request is unsuccessful, the content type will be set to "text/plain" and the body will contain a text error message.

Example

Here is an example to issue a request from the command line using curl or the Ioto url command using a CloudAPI token:

curl

curl -X POST https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/tok/generic/find \
     -H 'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
     -H 'Content-Type: application/json' \
     -d '{"deviceId": "ZXXXXXXXXX", "_type": "Store"}'

url

url https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/tok/generic/find \
    'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
    '{deviceId: "ZXXXXXXXXX", _type: "Store"}'

Note: the url command is a utility command that is installed with the Ioto CLI. It can automatically sense the arguments as either headers, or body data. JSON body data can be passed as JSON5 (like JS) and can thus omit quotes on property keys and setting the Content-Type header.

Read More

• API Authentication

Ioto APIs

Controller	Description
Account	Account API
Action	Action API
Alert	Alert API
Dashboard	Dashboard API
Device	Device API
Generic	Generic Data Access API
Metric	Metric API
Provision	Device Provisioning API
Store	Key/Value Store API
User	User API