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 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.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 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.
- 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.
