Getting started
Overview¶
This guide explains how to use the Firewall Management API. After reading this guide, you should be able to manage firewalls, check their status, perform operations on them, and manage groups of firewalls.
Pre-requisites¶
You must have a set of API credentials (service principal) to be able to call the Firewall Management API. For more information refer to the appropriate quick start guide:
- Sophos Partners: Read the Partner Getting Started guide first.
- Enterprise customers: If you use Sophos Enterprise to manage multiple tenants, read the Organization Getting Started guide first.
- Other customers: Read the Tenant Getting Started guide first.
Terminology¶
Before you use the Firewall Management API, here are a few terms you should know:
- Firewall: A hardware or virtual appliance that protects your network.
- Firewall groups: A group of firewalls. You can configure all firewalls in a group simultaneously. You can also create nested child groups.
- Firmware: The software that runs on a firewall. The firmware is versioned and can be updated.
Making API requests¶
You can make the API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.
When using curl, a request to the Endpoint API has the following general form:
curl -X <method> -H "Authorization: Bearer <jwt>" -H "X-Tenant-ID: <tenant-id>" <data-region>/<path>
The command includes the following placeholders:
<method>: The request method. For the Endpoint API, this is eitherGETorPOST.<tenant-id>: The ID of the tenant you want to query.<jwt>: The JWT access token returned when the IDP authenticates the service principal.<data-region>: The regional API host in the data geography where the tenant data is located.<path>: The request path for the API operation, for examplefirewall/v1/firewall-groups.
The API descriptions in this guide only specify the request method and path. For example:
POST /firewall/v1/firewall-groups
To make an actual API request, you must expand this to the full form shown above.
All API requests return HTTP status codes 200 or 201 when successful.
Firewall operations¶
List firewalls¶
To list firewalls, call:
GET /firewall/v1/firewalls
Response: This contains a list of Firewall objects.
{
"items": [
{
"id": "39df20ba-7330-41ae-9071-0ac682bdd1e6", // Firewall unique ID.
"cluster": { // Present only if the firewall is in a
// cluster with another.
"id": "6a72014b-ae91-4d50-807a-d3601e44b9b7",
"mode": "activeActive",
"status": "primary", // Role of this firewall within the cluster.
"peers": { // Peer firewall in cluster.
"id": "e2875239-be72-4b3e-85f2-37ec51fe3cbd",
"serialNumber": "SFDemo-ta-xgs107w-07"
}
},
"tenant": { // Tenant to which this firewall belongs.
"id": "3e382b8e-49fd-4cd9-8360-a364371d7650"
},
"serialNumber": "C01001JYCGB4J30",
"group": { // Group to which this firewall belongs.
// Not present if the firewall isn't in
// a group.
"id": "ab83681f-aff6-4c2d-b0e5-1e9960fa5ce7",
"name": "Bangalore Group"
},
"hostname": "FW-1",
"name": "fw-label",
"externalIpv4Addresses": [
"111.93.156.226",
"125.16.229.10"
],
"firmwareVersion": "SF01V_SO01_19.0.0.294",
"model": "SFVUNL_SO01_SFOS 19.0.0 GA-Build294",
"status": {
"managing": "approvalPending",
"reporting": "approvalPending",
"connected": true,
"suspended": false
},
"statusChangedAt": "2022-04-01T17:49:26.400Z",
"capabilities": [
"sdwanGroup"
],
"geoLocation": {
"latitude": "20.64", // Geo-location latitude value as a string
"longitude": "22.43" // Geo-location longitude value as a string
},
"createdBy": {
"id": "9f0a6bf4-1fa6-407a-aa1d-4b888a626bb3",
"type": "user",
"name": "Joe Bloggs",
"accountType": "tenant",
"accountId": "98be8a40-ea9e-488e-b7d1-200d924cdb54"
},
"createdAt": "2021-10-25T05:27:39.467Z",
"updatedAt": "2022-04-01T18:08:26.472Z",
"updatedBy": {
"id": "0ab38272-0d0c-4425-936c-8e45a289169e",
"type": "user",
"name": "Jane Doe",
"accountType": "partner",
"accountId": "b2f5d2d4-a041-494c-a3a2-a45219b6349a"
}
}
],
"pages": {
"current": "1", // The current page, starting from 1.
"total": "1,", // Total number of pages. Present only if
// pageTotal=true was passed in the API call
"size": "100,", // The page size. You can change this by passing
// pageSize=<number> as a query param
"maxSize": "1000,", // Maximum page size allowed
"items": 1 // Present if pageTotal=true was passed in the API call
}
}
Perform an action on a firewall¶
Call:
POST /firewall/v1/firewalls/{firewallId}/action
Request body:
{
"action": "approveManagement"
}
Response:
{
"status": "succeeded",
"action": "approveManagement"
}
Currently, you can only perform one action on a firewall: approve it being managed from Sophos Fusion. In the future, this API may support more actions.
Change firewall attributes¶
To change a firewall's attributes, call:
PATCH /firewall/v1/firewalls/{firewallId}
Request body:
{
"name": "FW-1840", // New display name.
"geoLocation": { // New firewall location.
"latitude": "20.64",
"longitude": "122.43"
}
}
The response is the updated Firewall object. This has the same schema as an item from the response to the List firewalls operation above.
Delete firewall¶
To delete a firewall, you need its ID. Call:
DELETE /firewall/v1/firewalls/{firewallId}
Response:
{
"deleted": true
}
Check firmware upgrades¶
To check if a set of firewalls has upgrades available, you need its ID. Call:
POST /firewalls/actions/firmware-upgrade-check
Request body:
{
"firewalls": ["df1f8ccf-1223-46ed-9042-6672a8326b8c"] // max items is 1000 IDs
}
Response:
{
"firewalls": [ // upto 1000 objects
{
"id": "df1f8ccf-1223-46ed-9042-6672a8326b8c",
"serialNumber": "C01001JYCGB4J30",
"firmwareVersion": "18.5.1.326",
"upgradeToVersion": [
"19.0.0.294"
]
}
],
"firmwareVersions": [
{
"version": "19.0.0.294",
"bugs": [
"NC-6190 [API Framework] i18n config and actual config name(in tbldefaultconfigini18n) mapping issue",
"NC-7285 [AppFilter Policy] Importing Application filter policy (Using Import/Export option) changes the rules and list of applications within rules when any of the rule contains characteristics as cloud application.",
"NC-6224 [Authentication] OTP settings can't add Groups as OU",
"NC-6608 [Authentication] XG v18: AD Group import failing",
"NC-6799 [Authentication] csd service is in stopped state",
"NC-6911 [Authentication] Cannot export remote Users from XG",
"NC-7087 [Authentication] guest_user_purging opcode getting failed due to large payload size",
"NC-7249 [Authentication] Unable to get the password via SMS for the Guest User who already got password once."
],
"news": [
"Maintenance Release",
"FIPS 140-2 certified. Crypto Module on SFOS v18.5 MR2 (and future MRs of v18.5) is now FIPS 140-2 Level 1 certified for XGS series hardware as well as SFOS running on virtual machines.",
"Added support for GCM and suite-B ciphers for IPSec VPN. AES-GCM for IPSec significantly improves IPsec VPN performance.",
"Increased ideal timeout for IPsec remote access connections up to 6 hours.",
"MASQ rule for Route Based IPSec (RBVPN) will now use XFRM IP instead of WAN IP in the source NAT.",
"Improved MFA (TOTP) Authentication Added MFA support for the admin account. Added alert notification of admin account without MFA. Streamlined MFA admin experience with easier to discover and enable MFA configuration.",
"Active Directory enhancements for multiple group membership. Web UI will show all the groups that the user belongs to.",
"Certificate enhancements. More useful information about different certificate authorities. Easily find out locally added certificates, a certificate that has private keys. Easily download a copy of the public part of any certificate so that you can check/confirm."
],
"size": "400 MB"
}
]
}
Upgrade firmware¶
To upgrade a firewall (to a specified firmware version), call:
POST /firewall/v1/firewalls/actions/firmware-upgrade
Request body:
{
"firewalls": [ // upto 1000 objects
{
"id": "df1f8ccf-1223-46ed-9042-6672a8326b8c",
"upgradeToVersion": "19.0.0.294",
"upgradeAt": "2022-03-30T05:43:59.492Z"
}
]
}
Response:
{
"firewalls": [
{
"id": "df1f8ccf-1223-46ed-9042-6672a8326b8c",
"upgradeToVersion": "19.0.0.294",
"status": "success",
"upgradedAt": "2022-03-30T05:43:59.492Z"
}
]
}
Cancel firmware upgrade¶
To cancel a scheduled firewall upgrade, call:
DELETE /firewall/v1/firewalls/actions/firmware-upgrade?ids=df1f8ccf-1223-46ed-9042-6672a8326b8c
Response:
{
"deleted": true
}
Firewall group operations¶
List firewall groups¶
To list firewall groups, call:
GET /firewall/v1/firewall-groups
Response: This contains a list of Firewall Group objects.
{
"items": [
{
"id": "4f0ed382-ce28-4a9a-8a3d-f3d577ca7e72",
"name": "UK Office",
"parentGroup": {
"id": "b88df1aa-1fc2-472b-983d-d77f5c96e525"
},
"tenant": {
"id": "3e382b8e-49fd-4cd9-8360-a364371d7650"
},
"lockedByManagingAccount": false, // 'true' if this group is partner-managed.
"firewalls": { // A preview of the firewalls in this group.
"total": 10,
"itemsCount": 5,
"items": [
{
"id": "df1f8ccf-1223-46ed-9042-6672a8326b8c"
},
{
"id": "97483e58-55d7-44fb-b03f-9422f106ef66"
},
{
"id": "7e5605c1-da16-4995-9679-767a8b79328d"
},
{
"id": "8e5605c1-da16-4995-9679-767a8b79328d"
},
{
"id": "4e5605c1-da16-4995-9679-767a8b79328d"
}
]
},
"configImport": { // Status of importing the configuration
// of this group from a source firewall.
"sourceFirewall": {
"id": "902967e4-3df9-4dd0-8e23-1c917802b44c"
},
"percentComplete": 100,
"status": "success",
"errors": [] // Configuration importing errors.
},
"createdBy": {
"id": "97483e58-55d7-44fb-b03f-9422f106ef66",
"type": "user",
"name": "example",
"accountId": "97483e58-55d7-44fb-b03f-9422f106ef66",
"accountType": "customer"
},
"createdAt": "2022-03-30T05:43:59.492Z",
"updatedBy": {
"id": "97483e58-55d7-44fb-b03f-9422f106ef66",
"type": "user",
"name": "example",
"accountId": "97483e58-55d7-44fb-b03f-9422f106ef66",
"accountType": "customer"
},
"updatedAt": "2022-03-30T05:43:59.492Z"
}
],
"pages": {
"current": 1,
"total": 1,
"items": 1,
"size": 100,
"maxSize": 1000
}
}
Create firewall group¶
The following example shows how to create a firewall group.
POST /firewall/v1/firewall-groups
Request:
{
"name": "Test group", // Name of the firewall group. Must be unique.
"configImportSourceFirewallId": "df1f8ccf-1223-46ed-9042-6672a8326b8c", // The source firewall from which
// the initial configuration should
// be imported.
"assignFirewalls": [ // IDs of firewalls to add to the group.
"df1f8ccf-1223-46ed-9042-6672a8326b8c",
"97483e58-55d7-44fb-b03f-9422f106ef66",
"7e5605c1-da16-4995-9679-767a8b79328d"
],
"parentGroupId": "ab1f8ccf-1223-46ed-9042-6672a8326b8c" // Firewall group the new group be added under.
}
The response is a new Firewall Group object. This has the same schema as an item from the response to the List firewall groups operation above.
Update firewall group¶
The following example shows how to update a firewall group.
PATCH /firewall/v1/firewall-groups/{groupId}
Request body:
{
"name": "Updated group",
"assignFirewalls": [
"df1f8ccf-1223-46ed-9042-6672a8326b8c",
"97483e58-55d7-44fb-b03f-9422f106ef66"
],
"unassignFirewalls": [
"7e5605c1-da16-4995-9679-767a8b79328d"
]
}
The response is the updated Firewall Group object.
Delete firewall group¶
The following example shows how to delete a firewall group.
DELETE /firewall/v1/firewall-groups/{groupId}
Response:
{
"deleted": true
}
Get firewall synchronization status¶
To get synchronization status of firewalls in a group, call:
GET /firewall/v1/firewall-groups/{groupId}/firewalls/sync-status
Response:
{
"items": [
{ // One object per firewall.
"firewall": {
"id": "902967e4-3df9-4dd0-8e23-1c917802b44c"
},
"status": "inSync", // Other possible values are: notAvailable,
// syncing, outOfSync, and suspended.
"lastUpdatedAt": "2022-05-18T11:20:26.657+00:00"
}
],
"pages": {
"current": 1,
"total": 1,
"items": 1,
"size": 100,
"maxSize": 1000
}
}
MDR operations¶
Retrieve mdr-threat-feed for given firewall¶
To retrieve mdr-threat-feed for given firewall, call:
GET /firewalls/{firewallId}/mdr-threat-feed
Response: This returns the TransactionReference for GET call .
{
"transactionId": "3b66d11d-f7c0-45cf-b290-17924c0a31ee"
}
Now call the GET /firewalls/{firewallId}/transactions/{transactionId} to Get the Transaction
Singleton Object response
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "success",
"createdAt": "2012-06-26T11:55:36.100Z",
"finishedAt": "2012-06-26T11:59:36.100Z",
"expiryAt": "2012-07-25T11:55:36.100Z",
"response":
{ // ****** Below Data recieved from Firewall ********** //
"enabled":"true",
"action":"logOnly/logAndDrop",
"lastUpdatedAt":"2023-05-31T24:15:09Z"
}, // ****** Ends Here ******* //
"request": {
"method": "GET",
"path": "firewalls/2ba7f8ea-691c-4f03-862e-3cefb1028132/mdr-threat-feed"
}
}
Patch mdr-threat-feed for given firewall¶
The following example shows how to patch mdr-threat-feed for a given firewall.
PATCH /firewalls/{firewallId}/mdr-threat-feed/settings
Request:
{
"enabled": true, //ThreatFeed Enabled Indicator
"action": "logOnly" //ThreatFeed Action (logOnly or logAndDrop)
}
Response: This returns the TransactionReference for PATCH call .
{
"transactionId": "3b66d11d-f7c0-45cf-b290-17924c0a31ee"
}
The response is a TransactionReference for the PATCH call
Create indicators of mdr-threat-feed for given firewall¶
The following example shows how to create indicators of mdr-threat-feed for a firewall.
POST /firewalls/{firewallId}/mdr-threat-feed/indicators
Request body:
{"indicators":[{"type":"ipv4-addr","value":"1.2.3.4"}]}
The response is a TransactionReference for the POST call.
Response For Semantic validation failure at firewall
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "error",
"createdAt": "2012-06-26T11:55:36.100Z",
"finishedAt": "2012-06-26T11:59:36.100Z",
"expiryAt": "2012-07-25T11:55:36.100Z",
"response":
{ // ****** Below Data recieved from Firewall ********** //
"error": "indicatorExists",
"message": "Indicators are already present."
}, // ****** Ends Here ******* //
"request": {
"method": "POST",
"path": "firewalls/2ba7f8ea-691c-4f03-862e-3cefb1028132/mdr-threat-feed/indicators"
}
}
Array Object response
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "success",
"createdAt": "2012-06-26T11:55:36.100Z",
"finishedAt": "2012-06-26T11:59:36.100Z",
"expiryAt": "2012-07-25T11:55:36.100Z",
"response":
{ // ****** Below Data recieved from Firewall ********** //
"items":[
{
"type": "ipv4-addr",
"value": "5.23.2.2"
},
{
"type": "domain-name",
"value": "www.example.com"
},
{
"type": "url",
"value": "www.example.com/index.php"
}
]
}, // ****** Ends Here ******* //
"request": {
"method": "POST",
"path": "firewalls/2ba7f8ea-691c-4f03-862e-3cefb1028132/mdr-threat-feed/indicators"
}
}
Partial Success at firewall
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "partialSuccess",
"createdAt": "2012-06-26T11:55:36.100Z",
"finishedAt": "2012-06-26T11:59:36.100Z",
"expiryAt": "2012-07-25T11:55:36.100Z",
"response":
{ // ****** Below Data recieved from Firewall ********** //
"items":[
{
"type":"domain-name",
"value": "www.example.com"
},
{
"type":"url",
"value": "www.example.com/index.php"
},
{
"type":"ipv4-addr",
"value": "123.43.2.2"
},
{
"type":"ipv4-addr",
"value": "165.23.65.12"
}
],
"errors":{
"duplicateMDRIndicators":{
"items":[{
"type":"ipv4-addr",
"value": "65.34.2.2"
}]
},
"invalidMDRIndicators":{
"items":[{
"type":"ipv4-addr",
"value": "265.34.2.2"
}]
}
}
}, // ****** Ends Here ******* //
"request": {
"method": "POST",
"path": "firewalls/2ba7f8ea-691c-4f03-862e-3cefb1028132/mdr-threat-feed/indicators"
}
}
Delete All IoCs Of Mdr-Threat-Feed For Given Firewall¶
The following example shows how to delete all IoCs ff mdr-threat-feed for a given Firewall.
DELETE /firewalls/{firewallId}/mdr-threat-feed/indicators
The response is a TransactionReference for the DELETE call.
Delete Given IoCs Of Mdr-Threat-Feed For Given Firewall¶
The following example shows how to delete given IoCs of mdr-threat-feed for a given Firewall.
POST /firewalls/{firewallId}/mdr-threat-feed/indicators/delete
Request body:
{"indicators":[{"type":"ipv4-addr","value":"1.2.3.4"}]}
The response is a TransactionReference for the DELETE call.
Search existing indicators of mdr-threat-feed for given firewall¶
The following example shows how to search existing indicators of mdr-threat-feed for a given Firewall.
POST /firewalls/{firewallId}/mdr-threat-feed/indicators/search
Request body:
{
"indicatorValues": [
"1.2.3.4" ] // Always Required - Specify indicators value.]
}
The response is a TransactionReference for the DELETE call.
Retrieve transaction by Id for given firewall¶
The following example shows how to retrieve transaction by Id for a given firewall.
A transaction object represents a long running operation. A client can poll on its endpoint as soon as the original request's call returns. A transaction can be in the following states: 'pending','started' and 'finished'.Each transaction has a "poll count" which is used to determine the number of times the transaction has been retrieved from the database. Each transaction in state "finished" has a result which contains the response body and the request indicating the originating API performing the transaction. Transaction objects have a retention policy of 30 days, after which they get deleted
GET /firewalls/{firewallId}/transactions/{transactionId}
The response is the Transaction Object denoting the status as well as the response which would depend on API which was executed.
Response
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "success",
"createdAt": "2012-06-26T11:55:36.100Z",
"finishedAt": "2012-06-26T11:59:36.100Z",
"expiryAt": "2012-07-25T11:55:36.100Z",
"response":
{ // ****** Below Data recieved from Firewall ********** //
"enabled":"true",
"action":"logOnly/logAndDrop",
"lastUpdatedAt":"2023-05-31T24:15:09Z"
}, // ****** Ends Here ******* //
"request": {
"method": "GET",
"path": "firewalls/2ba7f8ea-691c-4f03-862e-3cefb1028132/mdr-threat-feed/settings"
}
}
The transaction's poll count is updated incrementally with every retrieval operation. These have a retention policy of 30 days,post which they are deleted by a scheduled batch job run.
Import/Export Operations¶
The Import/Export APIs let you export a firewall's configuration to a downloadable archive, and import a previously exported archive into one or more target firewalls. Both operations are asynchronous: the initial call returns a transactionId, and the caller polls a transaction endpoint to obtain the final result.
Note: unlike the Retrieve Transaction endpoint used by MDR operations, import/export transactions are polled on a shared endpoint that does not include a firewallId in the path (see Retrieve Import/Export Transaction).
Export firewall configuration¶
To trigger a configuration export for a given firewall, call:
POST /firewalls/{firewallId}/export
Request body:
{
"fullExport": true, // Required - true to export the full config, false to export selected entities.
"includeDependency": false, // Optional, only when fullExport is false. Defaults to false.
"exportEntities": ["<entity>", "<entity>"] // Required when fullExport is false; must be omitted when fullExport is true.
}
Validation rules:
- When
fullExportistrue, neitherexportEntitiesnorincludeDependencymay be supplied. - When
fullExportisfalse,exportEntitiesis required (must contain at least one entity name) andincludeDependencyis optional.
Valid values for exportEntities are drawn from the ExportableEntity enum:
Show all exportable entity names
AccessTimePolicy, AdminAuthentication, AdministrationProfile, AdminSettings, AdvancedConfiguration, AdvancedSMTPSetting, Alias, AntiSpamEmailArchiver, AntiSpamQuarantineDigestSettings, AntiSpamRules, AntiSpamTrustedDomain, AntiVirusFTP, AntiVirusHTTPScanningRule, AntiVirusHTTPsConfiguration, AntiVirusHTTPSScanningExceptions, AntiVirusMailSMTPScanningRules, ApplicationClassification, ApplicationClassificationBatchAssignment, ApplicationFilterCategory, ApplicationFilterPolicy, ApplicationObject, ARPConfiguration, ArpFlux, ATP, AuthCTA, AuthenticationServer, AuthThinclient, AVASAddressGroup, AWSVPC, AzureADSSO, BackupRestore, BookmarkManagement, BridgePair, BridgeStaticEntry, CellularWAN, CellularWANSettings, Certificate, CertificateAuthority, ChromebookSSOLogin, CliDhcp, ClientlessUser, ConnectWiseConfiguration, ContentConditionList, CountryGroup, CreateUnboundedLag, CreateUnboundedLagTap, CreateUnboundedVlan, CRL, CrVlanTag, CustomView, DataControlList, DataManagement, DataTransferPolicy, DecryptionProfile, DefaultCaptivePortal, DefaultInternetScheme, DefaultWebFilterNotificationSettings, DHCP, DHCPBinding, DhcpLeaseOverIpSec, DHCPRelay, DHCPServer, DHCPServerIpv6, DHCPV6, DHCPV6Binding, DiagnosticsSettings, DirectWebProxyAuthentication, DKIMSigning, DKIMVerification, DNS, DNSHostEntry, DNSRequestRoute, DoSBypassRules, DoSSettings, DynamicDNS, EACAppConfiguration, EditBridgeMember, EmailConfiguration, ExceptionPolicy, FileType, FirewallAuthentication, FirewallRule, FirewallRuleGroup, FormTemplate, FourEyeAuthenticationDeAnonymize, FourEyeAuthenticationSettings, FQDNHost, FQDNHostGroup, FqdnHostSetting, GatewayConfiguration, GatewayHost, GreRoute, GreTunnel, GuestUser, GuestUserSettings, HAConfigure, HealthCheckProfile, Hotfix, Hotspot, HttpProxy, Interface, InternetScheme, IPHost, IPHostGroup, IPSCustomSignature, IPSecRoute, IPSFullSignaturePack, IPSPolicy, IPSSwitch, IPTunnel, IPV4ParentProxy, IPV6ParentProxy, IviewCustomLogo, L2TPConfiguration, L2TPConnection, LAG, LagManagement, Letsencrypt, LinkFailover, LinkManagement, LiveUserDisconnect, LocalServiceACL, MACHost, MalwareProtection, Messages, MTAAddressGroup, MtaBlockedSenders, MTADataControlList, MTASPXConfiguration, MTASPXTemplates, MulticastConfiguration, MulticastRoute, NATRule, NetFlowConfiguration, Notification, Notificationlist, Oauth2, OTPSettings, OTPTokens, OverridePolicy, OverridePolicyTokenList, ParentProxy, PatternDownload, PIMDynamicRouting, PopImapScanning, POPIMAPScanningPolicy, PPTPConfiguration, ProtocolSecurity, ProxyArp, QoSPolicy, QoSSettings, RealServers, RED, REDDevice, RelaySettings, ReportNotification, ReverseAuthentication, RoutePrecedence, RouterAdvertisement, Schedule, SDWANPolicyRoute, SDWANProfile, SelfSignedCertificateAuthority, ServiceGroup, ServiceParam, Services, SiteToSiteClient, SiteToSiteServer, SmarthostSettings, SMSGateway, SMTPPolicy, SNMPAgentConfiguration, SNMPCommunity, SNMPv3User, SophosAdaptiveLearning, SophosConnectClient, SpoofPrevention, SPXConfiguration, SPXTemplates, SSLBookmark, SSLBookmarkGroup, SSLTLSInspectionRule, SSLTLSInspectionSettings, SSLTunnelAccessSettings, SSLVPNAuthentication, SSLVPNPolicy, StaticARP, SupportAccess, SurfingQuotaPolicy, SYNCOTPTokens, SyslogServers, SystemModules, SystemServices, TAP, ThirdPartyFeed, Time, TrustedMAC, UnicastRoute, User, UserActivity, UserGroup, UserPortalAuthentication, VarPartitionUsageWatermark, VirtualHostFailoverNotification, VLAN, VoucherDefinition, VPNAuthentication, VpnConfiguration, VpnConnRemoveOnFailover, VpnConnRemoveTunnelUp, VPNFailoverGroup, VPNIPSecConnection, VPNPortalAuthentication, VPNProfile, WAFSessionManagementSettings, WAFSlowHTTP, WAFTLS, WebAuthentication, WebFilterAdvancedSettings, WebFilterCategory, WebFilterException, WebFilterNotificationSettings, WebFilterPolicy, WebFilterProtectionSettings, WebFilterSettings, WebFilterURLGroup, WebProxy, WiFi6Interface, WirelessAccessPoint, WirelessLocalAP, WirelessMeshNetworks, WirelessNetworks, WirelessNetworkStatus, WirelessProtectionGlobalSettings, XFRMInterface, ZeroDayProtectionSettings, Zone.
Response: This returns the TransactionReference for the POST call. Poll the Retrieve Import/Export Transaction endpoint to obtain the pre-signed download URL once the export has finished.
{
"transactionId": "3b66d11d-f7c0-45cf-b290-17924c0a31ee"
}
Initiate configuration import¶
To start a configuration import, call:
POST /firewalls/import
This endpoint does not accept a request body. The response contains a pre-signed PUT URL that you use to upload the configuration archive. The target firewalls and archive metadata are supplied later, via the Notify Upload Completion call.
Response:
{
"transactionId": "3b66d11d-f7c0-45cf-b290-17924c0a31ee",
"url": "https://<pre-signed-put-url>",
"method": "PUT",
"expiresAt": "2026-07-10T12:30:00.000Z",
"description": "Upload the configuration archive to this URL using an HTTP PUT before it expires."
}
Upload the archive against url (HTTP PUT) before expiresAt, then call the upload-complete endpoint below.
Notify upload completion¶
Once the archive has been uploaded to the pre-signed URL, notify the platform and supply the target firewalls and archive metadata:
POST /firewalls/import/{transactionId}/upload-complete
transactionId is the value returned by Initiate Configuration Import.
Request body:
{
"firewallIds": ["2ba7f8ea-691c-4f03-862e-3cefb1028132"], // Required - at least one, unique.
"checksumMd5": "d41d8cd98f00b204e9800998ecf8427e", // Required - hex-encoded MD5 of the uploaded archive.
"fileSizeBytes": 12345, // Required - archive size in bytes.
"secureMasterKey": "<string>", // Optional - secure master key associated with the import.
"performPartialImport": true // Optional - allow partial success per firewall. Defaults to true.
}
Response: the standard Transaction object, carrying per-firewall import progress inside response.
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "started",
"result": "notAvailable",
"createdAt": "2026-07-10T11:55:36.100Z",
"finishedAt": null,
"expiryAt": "2026-08-09T11:55:36.100Z",
"response":
{ // ****** Below data received from Firewall ********** //
"uploadStatus": "success",
"items": [
{ "firewallId": "2ba7f8ea-691c-4f03-862e-3cefb1028132", "status": "started", "result": "notAvailable" },
{ "firewallId": "df1f8ccf-1223-46ed-9042-6672a8326b8c", "status": "notStarted", "result": "notAvailable" }
]
}, // ****** Ends Here ******* //
"request": {
"method": "POST",
"path": "firewalls/import"
}
}
Notable status codes:
202 accepted: request accepted.400 badrequest: invalidtransactionId, emptyfirewallIds, invalidchecksumMd5, or non-positivefileSizeBytes.404 notFound: transaction not found / expired.409 conflict: transaction is in a state that does not accept upload completion (e.g. already completed or already marked failed).
Retrieve Import/Export transaction by Id¶
Both the export and import flows are polled on the same endpoint. Unlike the MDR-operations transaction endpoint, this one does not take a firewallId:
GET /firewalls/transactions/{transactionId}
transactionId is the value returned by the originating export or import request. The shape of response depends on which operation is being polled.
Configuration export transaction
Once the export has finished successfully, response carries a pre-signed GET URL for downloading the archive:
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "success",
"createdAt": "2026-07-10T11:55:36.100Z",
"finishedAt": "2026-07-10T11:59:36.100Z",
"expiryAt": "2026-08-09T11:55:36.100Z",
"response":
{ // ****** Below data received from Firewall ********** //
"url": "https://<pre-signed-get-url>",
"method": "GET",
"expiresAt": "2026-07-10T12:30:00.000Z",
"firewallId": "2ba7f8ea-691c-4f03-862e-3cefb1028132"
}, // ****** Ends Here ******* //
"request": {
"method": "POST",
"path": "firewalls/{firewallId}/export"
}
}
Configuration import transaction
Same shape as the response to Notify Upload Completion: a per-firewall items[] array reports progress alongside the overall uploadStatus.
{
"id": "15a7f8ea-691c-4f03-862e-3cefb102818e",
"status": "finished",
"result": "partialSuccess",
"createdAt": "2026-07-10T11:55:36.100Z",
"finishedAt": "2026-07-10T11:59:36.100Z",
"expiryAt": "2026-08-09T11:55:36.100Z",
"response":
{ // ****** Below data received from Firewall ********** //
"uploadStatus": "success",
"items": [
{ "firewallId": "2ba7f8ea-691c-4f03-862e-3cefb1028132", "status": "finished", "result": "success" },
{ "firewallId": "df1f8ccf-1223-46ed-9042-6672a8326b8c", "status": "finished", "result": "error" }
]
}, // ****** Ends Here ******* //
"request": {
"method": "POST",
"path": "firewalls/import"
}
}
While response.uploadStatus is pending, each response.items[].status will be notStarted — the archive upload has not completed yet, so the per-firewall imports have not yet been queued.
Note: firewall configuration import time may vary depending on the size and complexity of the configuration being imported, as well as the underlying specifications of the firewall model.
Import/export transactions follow the same 30-day retention policy as other firewall transactions.
Conclusion¶
See the API reference for a comprehensive description of the Firewall Management API.