Devices: CRUD Devices

The following endpoints are related to devices in the portal.

 

Create a device

Devices cannot be created on the portal.

Devices must be created on and connected to the IoT platform in order to show up on the portal.

 

Retrieve devices linked to an account

You can use the following endpoint within your custom pages in order to query all devices for the current tenant along with their last values. Note that only devices with data will be returned.

Summary

  • Endpoint: /device_list_in_tenant
  • Method: GET
  • Required User Type: None, this works for all users
    • This even works for super users/admin, but they must be within a tenant

Response

A successful response will return a list of objects. Each object represents a different device linked to the tenant and contains all of the device's last values.

Example

Request URL

https://portal-example.mediumone.com/device_list_in_tenant

Response Data

[{
"device_data.device_id": "device_1",
"device_data.switch": "on"
},
{
"device_data.device_id": "device_2",
"device_data.button_press": "single"
}] 

 

Update a device

See Devices: CRUD Device Types in order to update a device's device type. There are no other fields to update for an individual device.

 

Link a device to an account as account admin

This endpoint will link a device to the current tenant.

Summary

  • Endpoint: /api/v2/devices/register/{{registration_code}}
  • Method: POST
  • Required User Type: Account Admin

 

Before Using Endpoint: Set Up Advanced Config

STEP 1: Go to Advanced Config

In your Super Admin account, go to "Developer > Advanced Config".

STEP 2: Enable Device Registration

Add the following key-value pair to the advanced config in order to enable device registration.

"DEVICE_REGISTRATION_ENABLED": true

STEP 3: Set Registration Tag

Add the following key-value pair to the advanced config.

"REGISTRATION_CODE_TAG": <value>

This configuration defines the Medium One tag that stores the registration code. The endpoint uses this to find the correct device to link to the tenant.

  • The default value is "raw.device_id"; if this tag stores your devices' registration code, then you do not need to add this key-value pair.
  • If you set the value as "", then you should use the device_id (API Basic User) as the registration_code in the endpoint.

STEP 4: Save Advanced Config

If these are your first entries in the advanced config, it should look like this:

{
"DEVICE_REGISTRATION_ENABLED": true,
"REGISTRATION_CODE_TAG": <value>
}

 

Path Parameters

  • registration_code - device's specific registration code
    • If "REGISTRATION_CODE_TAG" = "", then this should be the API Basic User of the device
    • Otherwise, the value provided should be found in the tag specified by "REGISTRATION_CODE_TAG"

 

Body Parameters

  • device_id - API Basic User of device you want to register
    • Type: string 
    • IMPORTANT: This is an optional parameter and is usually used if multiple devices have the same registration code. If you do not use this parameter, you must send an empty JSON body in your request. See the example for details.

 

Response

A successful response will return null.

 

Example

Request

/api/v2/devices/register/test_register

Request Body

{}

Response Data

null
 

 

Link a device to an account as super admin

You can use the following endpoint within your custom pages in order to link a device to an account as a super admin or super user.

Summary

  • Endpoint: /tenant_add_device
  • Method: GET
  • Required User Type: Super Admin or Super User

URL Parameters

  • device_id - API Basic User of device you want to link
  • tenant_id - ID of tenant you want to link device to
    • This is the API Basic User of the tenant without the "t_"
    • You can see the ID on the account's details page under "Account Information"

Response

A successful response is an empty 200 response.

Example

Request URL

https://portal-example.mediumone.com/tenant_add_device?device_id=test_device&tenant_id=26fd5c5b-272a-4020-ae49-a0a25c749048

Response Data

null

 

 

Unlink device from account as account admin

Coming soon!

 

Unlink device from account as super admin

You can use the following endpoint within your custom pages in order to remove a device from an account as a super admin or super user.

Summary

  • Endpoint: /tenant_remove_device
  • Method: POST
  • Required User Type: Super Admin or Super User

URL Parameters

  • device_id - API Basic User of device you want to remove
  • tenant_id - ID of tenant you want to remove device from
    • This is the API Basic User of the tenant without the "t_"
    • You can see the ID on the account's details page under "Account Information"

Response

A successful response is an empty 200 response.

Example

Request URL

https://portal-example.mediumone.com/tenant_remove_device?device_id=test_device&tenant_id=26fd5c5b-272a-4020-ae49-a0a25c749048

Response Data

null