Palo Alto Networks (PAN-OS API)

Connect a PAN-OS firewall's REST and XML APIs with a read-only admin's API key: what the agents read, what the estate harvest draws, and the read gate. Drafted from the public docs.

How-to · Updated 2026-10-28 · Describes release 0.1.164

Drafted from Palo Alto Networks' public documentation, then validated against a PA-VM running PAN-OS 11.2.15 (REST API version v11.2) in October 2026: the read-only administrator, the estate harvest (device, interfaces, routes, security rules with hit counts) and the traffic log read over the XML API. Other PAN-OS versions may answer differently. The paths, parameters and response shapes below are the ones the public docs show; Sources lists them. When your firewall answers differently, the harvest notes and the agent's evidence say so.

Overview

A Palo Alto Networks connection reads the firewall's management APIs, never its data path. The REST API (/restapi/v<major.minor>/…) reads the configuration: security rules, interfaces, zones, address objects and virtual routers. The XML API (/api/) reads the operational state and the logs: show commands, the security-policy and route lookups, and traffic, threat and system log retrieval. The Incident agent uses both to find which rule a flow meets and what the firewall dropped; the estate harvest puts the firewall, its interfaces and the traffic its rules allow on the estate map. On AWS the firewall runs as a VM-Series instance; connect its management interface.

A built-in skill, paloalto-flow-check, walks the agent through a flow that crosses the firewall. The agent sees it only in a workspace with a Palo Alto Networks connection.

Setup

Before you start

Installation

On the firewall:

  1. Choose the role. The simplest is the dynamic role Superuser (read-only). For a narrower one, create an Admin Role profile under Device > Admin Roles. On its REST API tab set the resources the agent reads to Read Only (Ethernet interfaces, zones and virtual routers under Network, addresses under Objects, security rules under Policies) and disable the rest. On its XML API tab enable Operational Requests (the show commands and the two lookups) and Log; enable Configuration only if the agent should also read configuration subtrees over the XML API. The harvest reads the configuration over REST, and the XML API tab offers only enable or disable, so Configuration is also the permission that writes. Leave Commit, User-ID Agent, Import, Export and Report disabled, and give the role no Web UI or Command Line access, so the administrator can only call the API. The platform's own gate below judges every XML API request whatever the role allows.
  2. Under Device > Administrators, add an administrator for the platform alone, such as aiops-reader, with that role. Palo Alto Networks recommends a separate admin account for API access; the firewall's logs then name the platform's calls, and its key can be revoked without touching anyone's login.
  3. Generate its API key with the XML API's type=keygen request, as a POST with the credentials in the form body rather than the URL, the way the docs show it: curl -X POST "https://<firewall>/api/?type=keygen" -H "Content-Type: application/x-www-form-urlencoded" -d 'user=aiops-reader&password=<password>'. Copy the <key> from the answer. The key belongs to that administrator: deleting it or changing its password invalidates the key.
  4. Set a key lifetime: Device > Setup > Management, edit Authentication Settings, API Key Lifetime (min) (1 to 525600 minutes; the default 0 means keys never expire), then commit. Palo Alto Networks recommends a short lifetime. When it elapses, generate a new key and replace it on Edit. Expire all API Keys on the same page revokes every key at once, for instance after one is exposed.

The platform sends the key in the X-PAN-KEY header, never as key= in the URL, where it would land in web server and proxy logs; a request through the connector that carries key or password in its query is refused. The read gate below is a floor, not a substitute for a read-only role.

Configuration

  1. Open Settings · Data in → Data sources and select Connect datasource.
  2. Under Type, choose Palo Alto Networks (PAN-OS API). Enter a Connection name; the connected list shows it, and the agent's tool is named after it (<name>_request).
  3. Fill the fields; the TLS-skip field sits under Advanced connection settings:
Field (portal label) API key Value
Management URL (https://<firewall>, without /restapi or /api) url The management interface
API key of a read-only administrator api_key The key from type=keygen for the dedicated API administrator; stored write-only
Virtual system (optional — blank = vsys1) vsys Set on a multi-vsys firewall; the harvest reads one virtual system
REST API version (optional — e.g. v11.1; blank = read from the firewall's software version) api_version Set only when the detected v<major>.<minor> is not a REST version your firewall serves
Skip TLS verify for a self-signed cert (optional — type: true) insecure true for the default self-signed management certificate
  1. Optionally, open Optional · describe this environment and say in What should AIOps know about it? what the firewall protects and which zones face the internet.
  2. Under Use this connection for, choose Investigate only and select Connect and verify.

The same connection through the API (POST /api/aiops/{tenant_id}/datasources, requires datasources.manage; the key goes in secret_values):

{
  "type_key": "paloalto",
  "name": "pa-edge",
  "description": "VM-Series in the inspection VPC; untrust faces the internet, trust holds the app subnets.",
  "config": {
    "url": "https://pa-fw.example.com",
    "vsys": "vsys1",
    "api_version": "v11.1",
    "insecure": "true"
  },
  "secret_values": {
    "api_key": "<API key>"
  },
  "role": "read",
  "enabled": true
}

Validation

Connect and verify, and Test on the row later, sends a GET to /api/?type=version with the key in X-PAN-KEY. You should see a dialog titled <connection name> is connected with Connected — verified from the control plane, and later in the row's Last test ok · HTTP 200 /api/?type=version — <response status="success"><result><sw-version>…. A 403 means the key is wrong or its role does not enable the XML API. The REST permissions show on the first harvest or rule read.

If something fails

The dialog shows Needs a fix, what to fix and the check's own detail; the row is saved either way. Select Edit, correct the field the detail names and save again, or select Retry once a cause outside the form (network, role) is fixed. Every verdict this connector produces is in Troubleshooting below.

Data collected

Tools the agent gets

Responses are capped at 20,000 characters per call.

Read surface

The XML API writes over GET as easily as it reads (type=config&action=set is a GET), so the method proves nothing there and the platform judges the request itself. What runs freely:

The full rule table is under The read/write gate in detail in Connections and remediation access.

Estate harvest

Harvest now on the row, the daily inventory job and an estate x-ray scan read show system info over the XML API (hostname, model, serial, software version, management address), then over REST Network/EthernetInterfaces, Network/Zones and Objects/Addresses, then show rule-hit-count for the security rulebase over the XML API (the rule hit counters), then over REST Policies/SecurityRules and Network/VirtualRouters, all of one virtual system. They become:

Deny rules are drawn with their action and usage and no interface links; disabled rules are counted, not drawn. Interfaces and rules are leaf detail: on the Estate map (in the product: /portal/estate) they show when you tick Show every object, rules and interfaces included or focus the firewall. The firewall counts for the map's firewall check and the x-ray report's Firewall line, and an enabled Palo Alto Networks connection counts on its own before the first harvest. A denied or failed read is a note on the harvest, never a crash, and what it would have listed is not marked stale. Not read yet: subinterfaces, shared-location objects, address groups, NAT rules, Panorama-pushed pre- and post-rules. A VM-Series firewall the AWS harvest also lists as an instance is joined to it by address (its management address, or an interface's, is the private address of the instance or of one of its network interfaces): it counts as one firewall, and its row in a service group carries the enabled rules and the connection that read them. An address two instances or two firewalls hold joins nothing.

Troubleshooting

What you see Cause What to do
failed · HTTP 403 /api/?type=version The key is wrong, past its API Key Lifetime, or void because its administrator's password changed or Expire all API Keys ran; or its role does not enable the XML API. Generate a new key with type=keygen and replace it on Edit, or enable the XML API in the role.
failed · ConnectError: … or a certificate error A management interface the platform cannot reach, or the self-signed certificate. Use a private-network agent, or insecure: true.
The harvest notes REST API version unknown show system info did not answer, so the v<major.minor> path could not be built. Fix the XML API access, or set REST API version on Edit.
The harvest notes HTTP 403 on a REST listing (paloalto GET /restapi/v11.1/Policies/SecurityRules: …) The role's REST API tab does not read that resource. Set it to Read Only; the next harvest fills it in.
The harvest notes paloalto GET /api/ show rule-hit-count: the vsys is not a vsys name … The virtual system is not a vsysN name, so the command was not sent. Set Virtual system to the vsysN name on Edit. Meanwhile the rules are drawn without hit counts.
The harvest notes paloalto GET /api/ show rule-hit-count: HTTP 403 … or … the answer is not a success The role cannot run the operational command, or the firewall answered it with an error. Check that Operational Requests is enabled on the role's XML API tab; if it is, pass the note to your platform contact. Meanwhile the rules are drawn without hit counts.
The harvest notes HTTP 400 on a REST listing The REST version or the location the harvest sends is not what this PAN-OS version expects. Set REST API version on Edit. This reader is validated on PAN-OS 11.2.15 with v11.2; on another version, pass the note to your platform contact.
An XML type=config&action=set, a commit or show config running answers Investigation connections are read-only. The write gate. Expected; name the rulebase or object subtree you need.

The generic verdict strings are explained in Test a connection and read the failure. Every connection status word is in the status and error reference.

Next steps

Sources