Copy page

Documentation

Manage Device Inventory

The discovered devices inventory is populated from the device sources connected to SecuriThings, and it is updated continuously as additional devices are discovered. A discovered device must be onboarded before it can be managed through the SecuriThings platform.

This guide covers retrieving discovered devices and onboarding them into your managed inventory.

Managed vs discovered

• Managed devices (GET /v1/devices) are managed through the SecuriThings platform.
• Discovered devices (GET /v1/discoveredDevices) come from the connected device sources and are not managed until they are onboarded.

Scenarios

• Discovery monitoring. Track newly reported devices and their onboarding status over time.
• Bulk onboarding. Onboard every device that is ready to onboard in a single task.
• Onboarding backlog reporting. Report devices that require enrichment before they can be onboarded.

List devices ready to onboard

Filter discovered devices by onboardingStatus to retrieve only the devices that can be onboarded. Omit the filter to retrieve all discovered devices, or filter by deviceSources.id, deviceType, vendor, discoveredAfter, or discoveredBefore.

Code
curl "https://api.securithings.com/v1/discoveredDevices?onboardingStatus=readyToOnboard&limit=100" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <token>"

Onboard devices

Onboarding is an asynchronous task. Collect the IDs of devices whose onboardingStatus is readyToOnboard, then execute an onboardDevice task:

Code
curl -X POST "https://api.securithings.com/v1/tasks" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <token>" \
     -d '{
       "taskType": "onboardDevice",
       "devices": [
         { "deviceId": "9ff559ee-38b6-11f1-81cb-465864a35d0a" },
         { "deviceId": "dc7d4ef1-6bf9-11f1-b083-d27bafcacdf8" }
       ]
     }'

Verify the task succeeded

The outcome of the onboarding request is reported by the task. Poll GET /v1/tasks/{id} until every device task has a status of completed, then read the result of each device task. A result of succeeded means the device was onboarded. See Asynchronous Tasks.

Retrieve an onboarded device

An onboarded device is part of your device inventory, and can be retrieved from the devices endpoint by its ID:

Code
curl "https://api.securithings.com/v1/devices/9ff559ee-38b6-11f1-81cb-465864a35d0a" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer <token>"