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=asc is
an optional string that sets the chronological order in which alerts
are displayed. asc is from oldest to newest. desc 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.
- 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.
