Skip to content


You can update the configuration settings, such as rules and policies, using the Application Programming Interface (API).

You can add, update, or delete configurations fully or partially.

You make changes to the XML strings or the .xml file.

You can apply the same configuration on more than one firewall using the API interface. You won't have to make changes to the individual modules and objects on each firewall's web admin console.

  • To use API configuration, go to Backup and firmware > API.
  • For details of the attributes to use in XML strings, see the API help.

You can use one of the following methods to update the configuration:

XML strings: Use the strings to make changes in individual rules, policies, settings, or objects. To know more, see How to use API.

You can enter the XML string in one of the following locations:

  • On the command-line interface of Sophos Firewall. Alternatively, use the operating system of the endpoint device from which you access the Sophos Firewall console.
  • In a browser's address bar. All leading browsers support XML strings.
  • In applications, such as Postman.

The .xml file: Use the file to make extensive changes to the configuration. Go to Backup and firmware > Import export, and export the configuration fully or partially. Extract the .xml file from the .tar file, and make the changes. Convert it to a .tar file again, and import the .tar file. For details, see Import export.

API configuration

Setting Description
API configuration Select to allow administrators with permissions to get or set the configuration using the API.

You need to give read-write permissions to allow the administrator to make configuration changes.

To create an administrator profile with the read-write permissions, go to Profiles > Device access.

We recommend that you give read-write permissions only for the required objects and settings.

To apply the profile to an administrator, go to Authentication > Users.
Allowed IP address IP addresses of hosts from which you can make the changes.

To get your IP address, search online. Alternatively, sign in to the web admin console. Go to Log viewer, select Admin from the list, and see the source IP address for your sign-in.

XML string and components

The XML string must contain the API controller, administrator sign-in request, and the configuration request. The following table shows the details of these components:

Component Description
API controller string https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add XML request here>

<Firewall IP>: IP address or hostname of Sophos Firewall.

<port>: Admin console HTTPS port you configured on Administration > Admin settings.
Administrator sign-in request <Request><Login><Username>admin</Username><Password>1234</Password></Login>
Configuration requests Get the configuration:

Add or update the configuration:

Delete the configuration:

For browsers, use the following XML string:

https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add the XML request here>

For the CLI, use the following XML string:

curl -k "https://<Firewall IP>:<port>/webconsole/APIController?reqxml=<Add the XML request here>"


Get request:<Request><Login><Username>admin</Username><Password>xyz123

Set request:<Request><Login><Username>admin</Username><Password>xyz123

Remove request:<Request><Login><Username>admin</Username><Password>xyz123

XML tags and attributes

XML tags Description
<Request> Used for sending the XML request.

Attribute: API version

<Request APIVersion="1800.1" IPS_CAT_VER="1"><Login> <Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login></Request>
<Login> Authenticates the administrator.

<Login><Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login>
<Username> Administrator's username.

<Password> Administrator's password.

<Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password>

You can use a plaintext password or an encrypted password. The encrypted password is in the .xml file. Alternatively, you can get it on the command-line console.

For more information, see Get the encrypted password for API requests.
<Get> Gets information for the tag you specify. For the attributes, see API help.

<Request><Login><Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Get><IPHost></IPHost></Get></Request>
<Set> Adds or updates based on the tag you specify. For the attributes, see API help.

<Request> <Login><Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Set operation="add"><IPHost> <Name>CustomIPHostTypeIPV4</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress></IPAddress></IPHost></Set></Request>

If you don't enter “operation” and its value ("add" or "update"), Sophos Firewall adds the configuration. If the configuration exists, it updates the configuration.
<Remove> Deletes the configuration. For the attributes, see API help.

<Request><Login><Username>admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Remove><IPHost><Name>CustomIPHostTypeIPV4</Name></IPHost></Remove></Request>
<Filter> <Key> Filter gets data for the criteria you specify in the tag <Key>. You can only apply a filter to the attribute Name.

Use <Key> within the <Filter> tag to specify the filter key and filter criteria.

<Request><Login><Username>admin</Username> <Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Get><IPHost><Filter><key name="Name" criteria="like">CustomIPHostTypeIPV4</key></Filter></IPHost></Get></Request>
<Response> Shows the response for your request.

Attribute: APIVersion
Attribute value: The response tag shows the active firmware API version. Configuration tags show the value you specified in the XML request.

<Response APIVersion="1800.1" IPS_CAT_VER="1"><Login><status>Authentication Successful</status></Login><IPHost transactionid=""><Status code="200">Configuration applied successfully.</Status></IPHost></Response>
<Status> Shows the configuration status based on the code.

Attribute: Status code
Attribute value: Code number

<Response APIVersion="1800.1" IPS_CAT_VER="1"><Login><status>Authetication Successful</status></Login><IPHost transactionid=""><Status code="200">Configuration applied successfully.</Status></IPHost></Response>

For the status codes, see API help.

API help

The API help shows the tags, attributes, and status codes. To see these, you must do the following:

  1. Download the API help.
  2. The home page shows the XML tags, attributes, and some status codes. For details about how to format the XML requests, scroll down the API help page.
  3. The left menu and the attributes for each module are similar to the web admin console. If you need more details about an attribute, see the corresponding help page.

API explorer

You can sign in and sign out users using the API.

When you sign in a user using API, in Current activities > Live users, the user's client type shows API client.

<MacAddress>00:0C:29:2D:D3:AC</MacAddress> </LiveUserLogin></Request>


https://<Sophos Firewall IP address>:4444/webconsole/APIController?reqxml=<Request><LiveUserLogin><UserName>sophos

Get the encrypted password for API requests

You can make API requests using a plaintext password or an encrypted password.

To get your encrypted password, enter the following command in the Advanced shell:

aes-128-cbc-tool -k Th1s1Ss1mPlygR8A -t 1 -s <password>

More resources

Back to top