Skip to content

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.


Get

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

Endpoint

1
POST /device/get

Authorized Role

1
user

JSON Body Fields

Field Type Required Notes
id string yes Device Claim ID

Response

Field Type Notes
id string
cloudId string
productId string
model string
test boolean
created date

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

1
POST /device/claim

Authorized Role

1
user

JSON Body Fields

Field Type Required Notes
id string yes Device claim ID
cloudToken string yes CloudID Token
accountId string yes Manager Account ID
test boolean Set to true for test devices

Response

Field Type Notes
id string
cloudId string
productId string
model string
test boolean
created date

Find

Endpoint

1
POST /device/find

Authorized Role

1
user

JSON Body Fields

Field Type Required Notes
id string
cloudId string
productId string

Response

Field Type Notes
id string
cloudId string
productId string
model string
test boolean
created date

Query Path

Field Type
hidden boolean
filter string
limit string
next object
prev object
index string

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

1
POST /device/register

Authorized Role

1
public

JSON Body Fields

Field Type Required Notes
id string yes Device Claim ID
accountId string Manager Account ID
cloudToken string CloudID Token
productToken string yes ProductID Token
test boolean Set to true for test devices
* undefined

Response

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

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

1
POST /device/release

Authorized Role

1
user

JSON Body Fields

Field Type Required Notes
id string yes Device claim ID
cloudToken string yes CloudID Token

Token/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

1
POST /device/token/release

Authorized Role

1
user

JSON Body Fields

Field Type Required Notes
id string yes Device claim ID
cloudToken string yes CloudID Token

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

1
POST /device/remove

Authorized Role

1
admin

JSON Body Fields

Field Type Required Notes
id string yes Device claim ID