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.
Parameter
Example
Protocol
https
Tenant-specific URIs
acmecorp.iot.paloaltonetworks.com
where
acmecorp
is the tenant ID (customer ID)
Note: A tenant is the organization that owns an IoT Security account.
Path
/pub/v4.0/
Function call
device
retrieves details about an individual device by MAC address.
device/ip
retrieves details about one or more devices by IP address.
device/list
retrieves the entire device inventory for a tenant.
alert/list
retrieves the entire list of security and system alerts.
vulnerability/list
retrieves the entire list of vulnerability instances.
alert/update
resolves a security alert.
vulnerability/update
resolves one or more vulnerability instances.
device/update
adds or removes one or more user tags to one or more devices.
tag/list
retrieves a list of user-defined tags for devices.
General parameters
customerid=acmecorp
indicates the customer ID.
offset=1
is an optional integer that sets the number of items to skip.
pagelength=20
is 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 differs by type: for alerts, it’s 200 items; for devices, it’s 10,000; and for vulnerabilities, it’s unlimited, which means it basically returns everything. Because of these high default values, we recommend setting the page length to a smaller number, especially for alerts and vulnerabilities.
Device-specific parameters
deviceid=34:02:86:44:65:36
specifies the MAC address of a device. For a static IP device, the device ID is its static IP address.
ip=192.168.10.121
specifies the IP address of a device.
detail=false
is an optional Boolean value requesting the level of device details to be returned. The default is
false
.
detail=true
enters detail mode, which returns more device properties; for example:
‘https://acmecorp.iot.paloaltonetworks.com/pub/v4.0/device?detail=true&customerid=acmecorp’
Alert-specific parameters
type=policy_alert
is an optional string that returns security alerts. This is the only type of alert supported.
resolved=yes
is an optional string that returns only resolved alerts.
no
is the default and returns only active alerts.
stime=2020-11-3T08:00Z
is an optional string that sets the start of a time range for alerts to retrieve. (It’s unnecessary to set
etime=now
or
etime=
<time>
because it is always treated as
now
.)
sortdirection=ascending
is an optional string that sets the chronological order in which alerts are displayed.
ascending
is from oldest to newest.
descending
is from newest to oldest and is the default.
sortfield=date
is an optional string that sets the field by which returned alerts are sorted. Currently only
date
is supported.
Vulnerability-specific parameters
name=CVE-2018-18568
is an optional string that retrieves all instances of a specific vulnerability among your devices.
type=vulnerability
is a required string. The value must be
vulnerability
.
status=confirmed
is an optional string that retrieves only confirmed vulnerabilities.
potential
retrieves potential but unconfirmed vulnerabilities. If no value is passed, both types of vulnerabilities are retrieved.
groupby=device
is a required string.
device
lists all devices that have the same vulnerability; that is, it lists all vulnerability instances.
vulnerability
lists all vulnerabilities.
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:
X-Key-ID: <key_id>
X-Access-Key: <access_key>
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 a rate limit. When queries are for
device
and
device/ip
, the rate limit is a maximum of 10 queries per second per tenant. When queries are for
device/list
, the rate limit is 1 query per second per tenant because of the intensive amount of data that can potentially be returned.
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
Value
Description
API Access Key
The API Access Key is your unique identifier used as the
"X-Access-Key:{key}"
request header required for authenticating API calls.
API Key ID
The API Key ID is your unique token used to authenticate the API Access Key. The request header used when running an API call is
"X-Key-Id:{key_id}"
.
The following steps describe how to generate the necessary key values.
  1. Log in to the IoT Security portal and click
    Preferences
    .
  2. In the User Role & Access section, click
    Create
    next to API Access Key and follow the online steps to create an access key.
  3. 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