Get Started with the IoT Security API
Learn what’s necessary to use the IoT Security API.
The following parameters are used in queries sent to the IoT Security API.
acmecorpis the tenant ID (customer ID)
A tenant is the organization that owns an IoT Security account.
deviceretrieves details about an individual device by device ID. This is typically its MAC address but when a device is configured as a static IP device, the device ID is its IP address.
device/ipretrieves details about one or more devices by IP address.
device/listretrieves the entire device inventory for a tenant.
profile/mappingretrieves a complete list of profile-category-vertical mappings.
alert/listretrieves the entire list of security and system alerts.
vulnerability/listretrieves the entire list of vulnerability instances.
alert/updateresolves a security alert.
vulnerability/updateresolves one or more vulnerability instances.
device/updateadds a user tag to one or more devices.
tag/listretrieves a list of user-defined tags for devices.
policy/recommendationretrieves all active policy rule recommendations or those for one or more device profiles.
When retrieving a list of items or details for a single item, the properties can be in any order within the returned JSON object.
customerid=acmecorpindicates the customer ID.
offset=1is an optional integer that sets the number of items to skip.
pagelength=20is an optional integer that sets the number of items in one response; that is, in one page. The maximum page length you can set is 1000. The default page length for alerts, devices, and vulnerability instances is 1000. Because of these high default values, we recommend setting the page length to a smaller number, especially for alerts and vulnerabilities.
deviceid=34:02:86:44:65:36specifies the MAC address of a device. For a static IP device, the device ID is its static IP address.
ip=192.168.10.121specifies the IP address of a device.
detail=falseis an optional Boolean value requesting the level of device details to be returned. The default is
detail=trueenters detail mode, which returns more device properties; for example:
stime=2020-11-3T08:00Zis an optional string that sets the start of a time range for devices to retrieve. This is the time when a device was last active. (It’s unnecessary to set
etime=<time>because it is always treated as
sortdirection=ascis an optional string that sets the alphanumeric order in which devices are displayed by MAC address.
ascindicates an ascending order from smallest to largest.
desc, which is the default, indicates a descending order from largest to smallest.
sortfield=MACis an optional string that sets the field by which returned devices are sorted. Currently only
type=policy_alertis an optional string that returns security alerts. This is the only type of alert supported.
resolved=yesis an optional string that returns only resolved alerts.
nois the default and returns only active alerts.
stime=2020-11-3T08:00Zis an optional string that sets the start of a time range for alerts to retrieve. (It’s unnecessary to set
<time>because it is always treated as
sortdirection=ascis an optional string that sets the chronological order in which alerts are displayed.
ascis from oldest to newest.
descis from newest to oldest and is the default.
sortfield=dateis an optional string that sets the field by which returned alerts are sorted. Currently only
name=CVE-2018-18568is an optional string that retrieves all instances of a specific vulnerability among your devices.
status=Confirmedis an optional string that retrieves only confirmed vulnerabilities.
Potentialretrieves potential but unconfirmed vulnerabilities. If no value is passed, both types of vulnerabilities are retrieved.
groupbyis a required string. It specifies how to group device vulnerability instances in query results:
groupby=devicegroups results by device ID. Each device ID and a single vulnerability are an item in the items list.
groupby=vulnerability(the default) groups results by vulnerability. Each vulnerability and the device IDs impacted are an item in the items list.
Authentication and authorization
IoT Security issues the API Access Key and its ID. To authenticate and authorize your requests, pass the access key and its ID by adding two extra request headers:
For your requests to be authorized, the access key must be active and the user who created the key must be an owner or administrator.
To prevent DoS (denial-of-service) attacks on our system, IoT Security imposes rate limits. When queries are for
device/list, the rate limit is a maximum of 60 queries per minute per tenant because of the intensive amount of data that can potentially be returned. For everything else, the rate limit is 180 queries per minute.
Before you can begin using the IoT Security API, you must generate the following from the IoT Security app:
- API Access Key
- API Key ID
API Access Key
The API Access Key is your unique token that’s used as the
"X-Access-Key: ACCESS_KEY"request header required for authenticating API calls.
API Key ID
The API Key ID is your unique identifier used to authenticate the API Access Key. The request header that’s used when running an API call is
The following steps describe how to generate the necessary key values.
- Log in to the IoT Security portal and click.Preferences
- In the User Role & Access section, clickCreatenext to API Access Key and follow the online steps to create an access key.
- View and download the access key and key ID, saving them in a secure location. Your code must include both when making calls to the API.You can later return to the Preferences page to view the key ID. However, for security reasons, it is not possible to view the actual key in the IoT Security portal.
Recommended For You
Recommended videos not found.