Device

The Device API manages device registation with the Builder.

When devices are first booted, they will "register" with the builder using their device ID (ClaimID). The device then remains under the management of the Builder until it is "claimed" by a user for management using the "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.

This is an internal API called by managers which supply a manager account ID.

Once a device has registered itself with the builder, a user can claim the device for management.
Claiming requires providing the unique device Claim ID and the Cloud ID Token.

The claim ID would typically be
printed on the device label during manufacturer. The cloud claim token can be found in the Builder tokens list for
the relevant device cloud.

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

user

Request Body

Field	Type	Required	Notes
id	string	yes	Device claim ID.
managerAccountId	string		Manager Account ID.
certArn	string		Certificate ARN.
cloudId	string	yes	Cloud ID.
deviceToCloudToken	string	yes	DeviceToCloud Token.
test	boolean		Set to true for test devices.

Response

Object Record.

Field	Type	Notes
device	object	Device object.
product	object	Product object.

Device

Device object.

Field	Type	Notes
id	string	Device ID.
accountId	string	Owning account ID.
managerAccountId	string	App account ID.
cloudId	string	Owning cloud ID.
productId	string	Owning product ID.
test	boolean	Device is a test device.

Product

Product object.

Field	Type	Notes
accountId	string	Owning account ID.
description	string	Product description.
id	string	Product ID.
name	string	Product name.
planId	string	Owning plan ID.
suspended	boolean	Product suspended.
url	string	Product URL.

Get

The Get API will fetch a device record by its ID (ClaimID).

Endpoint

POST /device/get

Authorized User Role

user

Request Body

Field	Type	Required	Notes
id	string	yes	Device Claim ID.

Response

Device Record.

Field	Type	Notes
id	string	Device ID.
accountId	string	Owning account ID.
managerAccountId	string	App account ID.
cloudId	string	Owning cloud ID.
productId	string	Owning product ID.
test	boolean	Device is a test device.

Find

Find matching devices.

Endpoint

POST /device/find

Authorized User Role

user

Request Body

Field	Type	Notes
id	string	Device Claim ID.
cloudId	string	Cloud ID.
productId	string	Product ID.

Query String Options

Field	Type
limit	number
next	object
prev	object

Response

Paged response.

Field	Type	Notes
data	array	An array of Device records.
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
id	string	Device ID.
accountId	string	Owning account ID.
managerAccountId	string	App account ID.
cloudId	string	Owning cloud ID.
productId	string	Owning product ID.
test	boolean	Device is a test device.

Lookup

Lookup a productId.

Endpoint

POST /device/lookup

Authorized User Role

user

Request Body

Field	Type	Required	Notes
product	string	yes	Product claim token.

Response

Product Record.

Field	Type	Notes
accountId	string	Owning account ID.
description	string	Product description.
id	string	Product ID.
name	string	Product name.
planId	string	Owning plan ID.
suspended	boolean	Product suspended.
url	string	Product URL.

Register

Register a device when manufactured.

When devices are first booted during manufacturing test, the Ioto device agent will "register" with the builder using its device ID (ClaimID). If the device has been claimed by a user, the API will return a response containing the API address of the managing device cloud and an access token. If the device has not been claimed, the "registered" field will be set to true in the response (alone).

To register, supply the device claim ID and the product token ID. If the device is a test device only, set the "test" field to true
so that the device will not count toward your Ioto agent subscription count.
.

Endpoint

POST /device/register

Authorized User Role

public

Request Body

Field	Type	Required	Notes
id	string	yes	Device Claim ID.
account	string		Manager Account ID if auto claiming.
cloud	string		Cloud ID if auto claiming.
product	string	yes	Product ID Token.
test	boolean		Set to true for test devices.
*	any

Response

Object Record.

Field	Type	Notes
api	string	API endpoint for the device cloud that claimed the device.
token	string	Access token for requests to the device cloud.
registered	boolean	Set to true when registered.
cloudType	string	Type of cloud hosting.
cloudName	string	Cloud name.
cloudRegion	string	Cloud geographical region.

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

user

Request Body

Field	Type	Required	Notes
id	string	yes	Device claim ID.
cloudId	string		Cloud ID for release by the manager.
callback	boolean		Callback the builder flag.
certArn	string		Certificate ARN.

Remove

Remove a device from the builder.

If the device has been claimed by a device cloud, it should be released before being removed.

Endpoint

POST /device/remove

Authorized User Role

admin

Request Body

Field	Type	Required	Notes
id	string	yes	Device claim ID.

RemoveAll

Remove all devices.

Endpoint

POST /device/removeAll

Authorized User Role

owner

Request Body

Field	Type	Required	Notes
productId	string	yes	Product ID.

Response

Number Record.