Device

Device Management API.

When devices are initialized with the Ioto agent, they will register with the Builder service using their device ID (ClaimID) at https://admin.embedthis.com/api. The device registration API is part of the Builder API. See Device Registration.

Once registered, the device then remains under the management of the Builder until it is "claimed" by a user for management using the "Device Claim" API. When claimed, the device is redirected to the device cloud when it next invokes the "register" API.

Claim

Claim a device for management by a device cloud.

Once a device has registered itself with the builder, a user can claim the device for management.
The claim ID would typically be printed on the device label during manufacturer.

A claim request may specify the device as a test device where it will not be counted towards the subscription device count.

Endpoint

POST /device/claim

Authorized User Role

claimDevice

Request Body

Field	Type	Required	Notes
id	string	yes	Device claim ID.

Response

The claimed device.

Field	Type	Notes
accessed	date	When the device was last accessed.
accountId	string	Owning manager account ID.
created	date	When the device was first claimed.
id	string	Device Claim ID.
product	string	Builder Product name.
productId	string	Builder Product ID.
test	boolean	Device is for test purposes.
version	string	Firmware version.
checked	string	Checked version.

Find

Find matching devices filtered by matching properties.

Endpoint

POST /device/find

Authorized User Role

user

Request Body

Field	Type	Role	Notes
id	string		Device Claim ID.
accountId	string	owner	App account ID. Required if using CloudAPI token.
productId	string		Product registration ID from the Builder product list.

Query String Options

Field	Type	Default	Role	Notes
index	string		owner	Database index name: primary or gs1.
limit	number			Number of items to retrieve.
next	object			Pagination token for the next page.
prev	object			Pagination token for the previous page.

Response

Paged response.

Field	Type	Notes
data	array	An array of devices owned by the user.
next	string	Paged cursor to use for the next page of items.
prev	string	Pages cursor to use for the previous page of items.

Device

Field	Type	Notes
accessed	date	When the device was last accessed.
accountId	string	Owning manager account ID.
created	date	When the device was first claimed.
id	string	Device Claim ID.
product	string	Builder Product name.
productId	string	Builder Product ID.
test	boolean	Device is for test purposes.
version	string	Firmware version.
checked	string	Checked version.

Get

The Get API will fetch a device by its ID. If you have the "owner" role, you can fetch the device for any account by providing an account ID. Otherwise, it will fetch the device for the authenticated account.

Endpoint

POST /device/get

Authorized User Role

user

Request Body

Field	Type	Required	Role	Notes
id	string	yes		Device Claim ID.
accountId	string		owner	App account ID.

Response

Device Record.

Field	Type	Notes
accessed	date	When the device was last accessed.
accountId	string	Owning manager account ID.
created	date	When the device was first claimed.
id	string	Device Claim ID.
product	string	Builder Product name.
productId	string	Builder Product ID.
test	boolean	Device is for test purposes.
version	string	Firmware version.
checked	string	Checked version.

GetCreds

Get IAM credentials.

Get credentials for use in the device that is hosted in a dedicated cloud.

This will create temprorary IAM credentials based on the configured Cloud.deviceRole (default IotoDeviceRole). These credentials can be used with appropriate AWS SDK or Ioto AWS Sigv4 APIs.

Endpoint

POST /device/getCreds

Authorized User Role

device

Response

A set of AWS IAM credentials that can be used with AWS APIs.

Field	Type	Notes
accessKeyId	string	AWS access key ID.
secretAccessKey	string	AWS secret access key.
sessionToken	string	AWS credentials session token.
expires	date	When the credentials expire.
region	string	AWS region.

GetSignedUrl

Get a signed URL to upload or download a file for the device.

Endpoint

POST /device/getSignedUrl

Authorized User Role

device

Request Body

Field	Type	Notes
id	string	Device claim ID.
command	string	File command to execute (get/put/delete).
filename	string	File name.
mimeType	string	MIME type.
size	number	File size in bytes.

Response

A signed URL string.

Provision

Provision a device with MQTT certificates.

After a device has been claimed for management by a user into a device cloud, the device can call "getCerts" to request provisioning of MQTT certificates to secure communications.

This call returns the certificate, private key and communications endpoint to use for secure MQTT communications with the device cloud.

Endpoint

POST /device/provision

Authorized User Role

device

Request Body

Field	Type	Required	Notes
id	string	yes	Device claim ID.

Response

MQTT certificate and endpoints for device communications.

Field	Type	Notes
accountId	string	App Account ID.
certificate	string	X.509 certificate.
endpoint	string	MQTT host endpoint for communciations.
id	string	Device ID.
key	string	X.509 certificate key.
port	number	MQTT TCP/IP port number.
thing	string	AWS IoT Core thing name for the device.
error	string
delay	number	Delay in seconds until the device block will be lifted.

Release

Release a device from management by a device cloud. Releasing a device returns it to the builder to be available for claiming by another cloud.

Endpoint

POST /device/release

Authorized User Role

releaseDevice

Request Body

Field	Type	Required	Notes
id	string	yes	Device claim ID.

Response

Device Record.

Field	Type	Notes
accessed	date	When the device was last accessed.
accountId	string	Owning manager account ID.
created	date	When the device was first claimed.
id	string	Device Claim ID.
product	string	Builder Product name.
productId	string	Builder Product ID.
test	boolean	Device is for test purposes.
version	string	Firmware version.
checked	string	Checked version.