Get Started with the PAN-OS XML API

PANOS and
Panorama
XMLAPIUsage
Guide
Version7.1
ContactInformation

CorporateHeadquarters:
PaloAltoNetworks
4401GreatAmericaParkway
SantaClara,CA95054
https://www.paloaltonetworks.com/company/contactsupport

AboutthisGuide

ThisAPIreferenceguidecoversthefeaturesandusageofthePANOSXMLAPI.Foradditionalinformation,refer
tothefollowingresources:

ForinformationonhowtoconfigureothercomponentsinthePaloAltoNetworksNextGenerationSecurity
Platform,gototheTechnicalDocumentationportal:https://www.paloaltonetworks.com/documentationor
searchthedocumentation.

Foraccesstotheknowledgebase,discussionforums,andvideos,refertohttps://live.paloaltonetworks.com.

Forcontactingsupport,forinformationonsupportprograms,tomanageyouraccountordevices,ortoopena
supportcase,refertohttps://www.paloaltonetworks.com/support/tabs/overview.html.

ForthemostcurrentPANOSandPanorama7.1releasenotes,goto
https://www.paloaltonetworks.com/documentation/71/panos/panosreleasenotes.html.
Toprovidefeedbackonthedocumentation,pleasewritetousat:documentation@paloaltonetworks.com.

PaloAltoNetworks,Inc.

www.paloaltonetworks.com

2016PaloAltoNetworks,Inc.PaloAltoNetworksisaregisteredtrademarkofPaloAltoNetworks.Alistofourtrademarkscanbefound
athttps://www.paloaltonetworks.com/company/trademarks.html.Allothermarksmentionedhereinmaybetrademarksoftheir
respectivecompanies.

RevisionDate:September21,2016

2 PANOSandPanorama7.1XMLAPIUsageGuide PaloAltoNetworks,Inc.
 GetStartedwiththePANOSXMLAPI
TousethePANOSXMLAPI,firstuseyouradmincredentialstogetanAPIkeythroughthekeygencommand
type.YoucanthenusetheAPIkeytotestasimplecall.

ThisguidetestsAPIrequestsusingcURLcommands.However,youcanuseotherAPItesting
toolssuchasPostmanandRESTClienttotestAPIrequests.

EnableAPIAccess
GetYourAPIKey
MakeYourFirstAPICall
ExploretheAPI

PaloAltoNetworks,Inc. PANOSandPanorama7.1XMLAPIUsageGuide 11

Copyright 2007-2015 Palo Alto Networks

EnableAPIAccess GetStartedwiththePANOSXMLAPI

EnableAPIAccess

TheAPIsupportsthefollowingtypesofAdministratorsandAdminroles:
Dynamicroles:Superuser,Superuser(readonly),Deviceadmin,Deviceadmin(readonly),Vsysadmin,
Vsysadmin(readonly)
RolebasedAdmins:Device,Vsys,Panorama.
AdminRoleprofilesenableordisablefeaturesonthemanagementinterfacesofthefirewallorPanorama,
XMLAPI,webinterface,andCLI.FormoredetailsonAdministrativeRoles,seethePANOSAdminstrators
Guide.

Asabestpractice,setupaseparateadminaccountforXMLAPIaccess.

EnableAPIAccess

Step1 SelectanAdminRoleprofile. GotoDevice>Admin Rolesandselectorcreateanadminrole.

Step2 Selectfeaturesavailabletotheadmin 1. SelecttheXML API tab.

role. 2. EnableordisableXMLAPIfeaturesfromthelist,suchas
Report,Log,andConfiguration.
3. SelectOKtoconfirmyourchange.

Step3 Assigntheadminroletoanadministrator SeeConfigureanAdministrativeAccount.

account.

12 PANOSandPanorama7.1XMLAPIUsageGuide PaloAltoNetworks,Inc.

Copyright 2007-2015 Palo Alto Networks

GetStartedwiththePANOSXMLAPI GetYourAPIKey

GetYourAPIKey

TousetheAPI,generatetheAPIkeyrequiredforauthenticatingAPIcalls.Requestparametersshouldbe
URLencodedwhenusedinHTTPrequests.

GetYourAPIKey

Step1 TogenerateanAPIkey,makeaURLrequesttothefirewallshostnameorIPaddressesusingthe
administrativecredentialsandtype=keygen:
curl -X GET 'https://firewall/api/?type=keygen&user=username&password=password'
AsuccessfulAPIcallreturnsstatus="success"alongwiththeAPIkeywithinthekeyelement:
<response status="success">
<result>
<key>gJlQWE56987nBxIqyfa62sZeRtYuIo2BgzEA9UOnlZBhU</key>
</result>
</response>
Step2 (Optional)RevokeanAPIkey.
YoucanchoosetorevokeandthenchangeanAPIkeyassociatedwithanadministratoraccountbychanging
thepasswordassociatedwiththeadministratoraccount.AnyAPIkeysthatweregeneratedusingtheprevious
credentialswouldnolongerbevalid.
GeneratinganAPIkeyusingthesameadministratoraccountcredentialsreturnsuniqueAPIkeyseverytime,
andallofthekeysarevalid.

ChangethemasterpasswordonyourfirewallinordertogenerateauniqueAPIkey.Ifyouhave
notchangedthefirewallmasterkeyfromthedefault,allfirewallswiththesame
username/passwordwillreturnthesameAPIkey.

PaloAltoNetworks,Inc. PANOSandPanorama7.1XMLAPIUsageGuide 13

Copyright 2007-2015 Palo Alto Networks

MakeYourFirstAPICall GetStartedwiththePANOSXMLAPI

MakeYourFirstAPICall

GetYourAPIKeytomakeyourfirstcalltothePANOSXMLAPI.

MakeYourFirstAPICall

Step1 MakeacURLcalltogetsysteminformation,whichreturnstheIPaddress,hostname,andmodelofyour
firewall.BesuretoincludetheAPIkey:
curl
'https://firewall//api/?type=op&cmd=<show><system><info></info></system></show>&key=a
pikey'
Step2 Confirmthattheresponsetotheaboverequestlookssimilartothis:
<response status="success">
<result>
<system>
<hostname>firewall</hostname>
<ip-address>10.27.0.8</ip-address>
<netmask>255.255.254.0</netmask>
<default-gateway>10.27.0.1</default-gateway>
<is-dhcp>no</is-dhcp>
<ipv6-address>unknown</ipv6-address>
<ipv6-link-local-address>fe80::21b:17dd:dedf:c04a/64</ipv6-link-local-address>
<ipv6-default-gateway />
<mac-address>00:1b:17:ff:c0:4a</mac-address>
<time>Wed Feb 10 13:03:32 2016</time>
<uptime>1 days, 19:35:51</uptime>
<devicename>firewall</devicename>
<family>3000</family>
<model>PA-3020</model>
<serial>001901000114</serial>
<sw-version>7.1.</sw-version>
<global-protect-client-package-version>2.0.0</global-protect-client-package-version>
<app-version>557-3138</app-version>
<app-release-date>2016/02/09 16:56:02</app-release-date>
<av-version>2261-2700</av-version>
<av-release-date>2016/02/09 15:26:53</av-release-date>
<threat-version>557-3138</threat-version>
<threat-release-date>2016/02/09 16:56:02</threat-release-date>
<wf-private-version>0</wf-private-version>
<wf-private-release-date>unknown</wf-private-release-date>
<url-db>paloaltonetworks</url-db>
<wildfire-version>27518-28208</wildfire-version>
<wildfire-release-date>2016/01/08 11:08:16</wildfire-release-date>
<url-filtering-version>2016.01.08.407</url-filtering-version>
<global-protect-datafile-version>1452328885</global-protect-datafile-version>
<global-protect-datafile-release-date>2016/01/09 08:41:25</global-protect-datafile-release-date>
<logdb-version>7.0.9</logdb-version>
<platform-family>3000</platform-family>
<vpn-disable-mode>off</vpn-disable-mode>
<multi-vsys>on</multi-vsys>
<operational-mode>normal</operational-mode>
</system>
</result>
</response>

14 PANOSandPanorama7.1XMLAPIUsageGuide PaloAltoNetworks,Inc.

Copyright 2007-2015 Palo Alto Networks

GetStartedwiththePANOSXMLAPI ExploretheAPI

ExploretheAPI

ThereareseveralwaysyoucanexploretheAPIandlearnhowtoconstructyourXMLrequests:
UsetheAPIBrowser
UsetheCLItoFindXMLAPISyntax
UsetheWebInterfacetoFindXMLAPISyntax

UsetheAPIBrowser

EachfirewallandPanoramaprovidesanAPIbrowserthatisaccessiblefromyourwebbrowser.TheAPI
browserletsyounavigatethroughandviewthecorrespondingXPathandAPIURL.

UsetheAPIBrowsertoExploretheAPI

Step1 Launchthewebinterface. 1. UseawebbrowsertonavigatetotheactualFQDNorIP

addressofyourfirewall:
https://firewall/
2. Loginwithyouradministratorcredentialswhenpromptedto
logintothewebinterface.

Step2 LaunchtheAPIBrowser. GototheAPIbrowserURLonyourfirewall:

https://firewall/api

PaloAltoNetworks,Inc. PANOSandPanorama7.1XMLAPIUsageGuide 15

Copyright 2007-2015 Palo Alto Networks

ExploretheAPI GetStartedwiththePANOSXMLAPI

UsetheAPIBrowsertoExploretheAPI(Continued)

Step3 Drilldowntoarequest. WhenyoufirstopentheAPIbrowser,theavailableRequestTypes

display.
1. Selectoneoftherequesttypestodrilldowntothenextlevel
oftheXPath.LetsstartwithConfigurationCommands,which
equatestotype=report:

2. Drilldownfurtheruntilyouselectarequestthatyouwantto
test.

16 PANOSandPanorama7.1XMLAPIUsageGuide PaloAltoNetworks,Inc.

Copyright 2007-2015 Palo Alto Networks

GetStartedwiththePANOSXMLAPI ExploretheAPI

UsetheAPIBrowsertoExploretheAPI(Continued)

Step4 Testarequest. 3. SelecttheURLtothentestthatrequestinthebrowser.

ThebrowsershowstheresultingXMLresponseinthebrowser:

PaloAltoNetworks,Inc. PANOSandPanorama7.1XMLAPIUsageGuide 17

Copyright 2007-2015 Palo Alto Networks

ExploretheAPI GetStartedwiththePANOSXMLAPI

UsetheAPIBrowsertoExploretheAPI(Continued)

AlongwiththeURL,theAPIbrowseralsoprovidestheXPathas
necessary,asshownhereforadescriptionofapredefined
application:

UsetheCLItoFindXMLAPISyntax

AnothermethodtodeterminetheappropriateXMLsyntaxandXPathforyourAPIcallsisthroughthe
commandlineinterface(CLI).Thismethodworksfortype=opandtype=configAPIcalls.
UsetheCLItoenabledebugmodeandthenruntheCLIcommandtoreceivethecorrespondingXMLand
XPathintheresponse.

UsetheCLItoFindXMLAPISyntaxandXPath

Step1 AccesstheCLI. UseanSSHclientorterminaltoaccessyourfirewallorPanorama

CLI.Formoreinformation,learnhowtoaccesstheCLIonyour
firewallorPanorama.

Step2 Enabledebugmode. Enterthefollowingcommand:

debug cli on
Step3 RunaCLIcommand. EnterandrunaCLIcommand.Example:
test url http://paloaltonetworks.com
<request cmd="op" cookie="7581536015878829"
uid="1206"><operations><test><url>http://paloaltonetw
orks.com</url></test></operations></request>

18 PANOSandPanorama7.1XMLAPIUsageGuide PaloAltoNetworks,Inc.

Copyright 2007-2015 Palo Alto Networks

GetStartedwiththePANOSXMLAPI ExploretheAPI

UsetheCLItoFindXMLAPISyntaxandXPath(Continued)

Step4 Usetheresultingresponsetocreatean UsethecmdvalueandtheXMLelementswithintheoperations

APIcall. tagtoformtheAPIcall:
https://firewall/api/?type=op&cmd=<test><url>htt
p://paloaltonetworks.com</url></test>&key=apikey
DependingontheCLIcommand,theXMLtagvaluesforcmd
willvary.Forexample,hereisaCLIcommandforshowing
firewallinformation:run show system info
ThecorrespondingAPIcalllookslikethis:
https://firewall/api/?type=op&cmd=<show><system>
<info></info></system></show>&key=apikey

UsetheWebInterfacetoFindXMLAPISyntax

YoucanusethewebinterfacealongwiththeavailabledebugconsoletoexploretheXMLandXPath
necessaryforyourAPIcalls.
Firstlogintothewebinterfaceandthenopenaseparatewindowwhereyoucanviewthecorresponding
XMLandXPath.

UsetheWebInterfaceandDebugConsoletoFindXMLAPISyntaxandXPath

Step1 Launchthewebinterface. LaunchawebbrowserandenterthefirewallsIPaddressor

hostname.Enteryourusercredentials.

Step2 Launchthedebugconsole. Inaseparatewebbrowserwindowortab,launchthedebug

console:
http://firewall/debug

PaloAltoNetworks,Inc. PANOSandPanorama7.1XMLAPIUsageGuide 19

Copyright 2007-2015 Palo Alto Networks

ExploretheAPI GetStartedwiththePANOSXMLAPI

UsetheWebInterfaceandDebugConsoletoFindXMLAPISyntaxandXPath(Continued)

Step3 Performtheactionyouwanttoreplicate Inthewebbrowser,navigatetothemenuanditemoractionthat

throughtheAPI. youwanttoperform.

ToaidinfindingtherelevantXML,selectClearinthedebug
consolejustbeforeyouselectthefinalmenuoraction.

Step4 ViewtheresultingXMLsyntaxinthe Inthedebugconsole,selectRefreshandthennavigatethroughthe

debugconsole. consoletothesyntaxrelatedtoyourchoiceoraction:

ExampleXMLwithindebugconsole:
<request cmd="op" cookie="3885378180190727">
<operations xml="yes">
<show>
<system>
<info/>
</system>
</show>
</operations>
</request>
ThecorrespondingAPIcalllookslikethis:
https://firewall/api/?type=op&cmd=<show><system>
<info></info></system></show>&key=apikey

20 PANOSandPanorama7.1XMLAPIUsageGuide PaloAltoNetworks,Inc.

Copyright 2007-2015 Palo Alto Networks