Skip to content

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

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
Login Access Token Browser A logged in user from a web browser app
CloudAPI Token Utility An admin service running in the cloud or on-premises

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

API Access

The Endpoint is of the form:

1
SITE/PATH

For example:

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

When using CloudAPI tokens, the request URLs are modified to insert a "/tok" prefix at the front of the URL PATH.

For example:

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

HTTP Methods

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

HTTP Headers

To authorize your request, include the authentication token as an Authentication HTTP header with your request.

You must also include an Origin header that is set to the domain name for your Device Manager.

All API requests use a HTTP Content-Type of application/json for both requests and responses.

For example:

1
2
3
Authorization: 1234567990X0C3B0ABF3CF81DZ....
Origin: mydomain.ioto.me
Content-Type: application/json

Example

Using the Ioto url command to issue a request using an CloudAPI token:

1
2
3
4
5
url POST \
    'https://xrp7t2deqh.execute-api.ap-southeast-1.amazonaws.com/tok/user/find' \
    'Authorization: 1234567990XXXXXXXXXXXXXXXX' \
    'Origin: mydomain.ioto.me' \
    '{deviceId: "ZXXXXXXXXX", _type: "Store"}'

Read More

Ioto APIs

Controller Description
Account Account 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