Manage devices

The Knox Configure v2 APIs provide functionalities for device management, allowing greater visibility into a device’s status and health. This tutorial focuses on how to manage your devices.

Prerequisites

Ensure that you have the necessary permissions to manage devices and obtain an authentication token. For more information, see Get started. Include your access token in the Authorization: Bearer <access_token> header of every request. Access tokens expire after 30 minutes.

Get device information

1. To retrieve essential details about your enrolled devices, such as model, IMEI, serial number, device state, and profile information, make a POST request to the /kc/v2/devices/getDevices endpoint. This operation requires the kc.devices:view scope.

2. In the request body, you can make use of the following optional parameters:

   • deviceIds — List of device IDs (IMEIs or serial numbers) to be retrieved.
   • profileIds — List of profile IDs to retrieve associated device IDs for.
   • deviceState — List of device states to filter by, such as Configured, Error, Unassigned, or UpdatesPushed.
   • pageNum — Page number to retrieve. The indexing count starts at 0.
   • pageSize — Number of items on a page. The default value is 25, and the maximum value is 100.
   • searchAfter — A pagination cursor used as an alternative to pageNum. Use the nextSearchAfter value returned in the previous response as the searchAfter value to retrieve the next page of results, which improves performance for large result sets.
   • sortBy — The value that results are sorted by. Possible values are updateTime, serviceEndDate, and lastSeenTime.
   • sortOrder — The order by which results are returned. Possible values are ascending and descending.

For example, the response of the following request body provides the details of those devices which have their IMEIs listed in deviceIds, whose state is Configured, and which are sorted by updateTime in descending order:

{
  "pageNum": 0,
  "pageSize": 25,
  "deviceIds": [
    "353227410022505",
    "RAKM2SVY64A"
  ],
  "profileIds": [],
  "deviceState": [
    "Configured"
  ],
  "sortBy": "updateTime",
  "sortOrder": "descending"
}

You can adjust the parameter values in the request body according to the kind of information you want to fetch. For detailed response schema, see POST /kc/v2/devices/getDevices.

Retrieve device logs

1. To retrieve the configuration logs for a specific device, make a POST request to the /kc/v2/devices/getDeviceLogs endpoint. This operation requires the kc.devices:view scope.

2. In the request body, you can make use of the following parameters:

   • deviceId — The unique identifier of the device. This is a required parameter.
   • oldImeiSn — The previous IMEI of the device, if the IMEI was exchanged.
   • pageNum — Page number to retrieve. The indexing count starts at 0.
   • pageSize — Number of items on a page. The default value is 25, and the maximum value is 100.

For example, the following request body retrieves the device logs for the device with ID 1597276, returning the first page with 25 results:

{
  "deviceId": "1597276",
  "pageNum": 0,
  "pageSize": 25
}

The response includes details such as error codes, lock pass codes, device state, update time, and any warnings that occurred during configuration. You can adjust the parameter values in the request body according to your needs. For detailed response schema, see POST /kc/v2/devices/getDeviceLogs.

Send a command to devices

1. To send a command to one or more devices, make a POST request to the /kc/v2/devices/sendCommand endpoint. This operation requires the kc.devices:manage scope.

2. In the request body, you can use the following parameters:

   • command — The command to be sent to devices. Possible values are REBOOT and FACTORY RESET. REBOOT instructs the device to turn off and back on again, and FACTORY RESET returns the device to factory default settings. This is a required parameter.
   • deviceIds — The IMEIs or serial numbers of the devices to send the command to. This is a required parameter.

For example, the following request body sends a REBOOT command to the devices with the specified IMEIs and serial numbers:

{
  "command": "REBOOT",
  "deviceIds": [
    "353227410022505",
    "RAKM2SVY64A"
  ]
}

You can adjust the command and device IDs based on the action you want to perform. For detailed response schema, see POST /kc/v2/devices/sendCommand.

Delete devices

1. To delete one or more devices from your Knox Configure tenant, make a POST request to the /kc/v2/devices/bulkDelete endpoint. This operation requires the kc.devices:manage scope.

2. In the request body, you can use the following parameter:

   • deviceIds — The IMEIs or serial numbers of the devices to be deleted. This is a required parameter.

For example, the following request body deletes the devices with the specified IMEIs and serial numbers:

{
  "deviceIds": [
    "353227410022505",
    "RAKM2SVY64A"
  ]
}

Ensure that you check the code and message in the response for any errors and handle them appropriately for your app. See Error codes for the full list of Knox Configure error codes. For detailed specification, see Knox Configure API reference.