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)
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 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/ip
retrieves details about one or more devices by IP address.
device/list
retrieves the entire device inventory for a tenant.
profile/mapping
retrieves a complete list of profile-category-vertical mappings.
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 a user tag to one or more devices.
tag/list
retrieves a list of user-defined tags for devices.
policy/recommendation
retrieves 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.
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 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.
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’
stime=2020-11-3T08:00Z
is 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=now
or
etime=<time>
because it is always treated as
now
.)
sortdirection=asc
is an optional string that sets the alphanumeric order in which devices are displayed by MAC address.
asc
indicates an ascending order from smallest to largest.
desc
, which is the default, indicates a descending order from largest to smallest.
sortfield=MAC
is an optional string that sets the field by which returned devices are sorted. Currently only
MAC
is supported.
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.
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
is a required string. It specifies how to group device vulnerability instances in query results:
groupby=device
groups 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:
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 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
Value
Description
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
"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