Skip to content
Last update: 2021-10-21

How to use the API

You can use the API to make configuration changes manually to XML strings.

Introduction

To make configuration changes using the API, do as follows:

  • Create an administrator profile with read-write permission for the modules you want to update.
  • Attach the administrator profile to an administrator record.
  • Allow the following activities:
    • API configuration.
    • API access from the IP address of the administrator's endpoint device.
    • Access to the administrative services of Sophos Firewall from the administrator's zone.
  • Submit the XML string. In this example, we enter the string in the address bar of a browser.

Create an administrator profile for making configuration changes

You create an administrator profile with read-write permission for objects and network.

  1. Go to Profiles > Device access and create an administrator profile with specific rights.

  2. Click Save.

    The following image shows an example of how to configure the settings:

    Administrator profile with read-write permission

Create an administrator

You create a user and add the administrator profile.

When you add a user with the API administrator profile, you can limit the administrator's rights based on the profile. Alternatively, you can use an existing administrator account.

  1. Go to Authentication > Users and click Add.
  2. Set User type to Administrator.
  3. Select the API administrator profile you created.
  4. To allow access for a specific time, select the Access time.
  5. To allow access only from specific IP addresses, select an option for Login restriction for device access.

  6. Click Save.

    The following image shows an example of how to configure the settings:

    Select an administrator profile

Allow API access

You allow API access for the administrator you created.

You turn on API configuration and allow API access from the administrator's IP address. You also allow access to the administrative services of Sophos Firewall.

  1. Specify the API configuration settings:

    1. Go to Backup and firmware > API.
    2. Select API configuration.
    3. For Allowed IP address, enter the IP address from which you'll make the API request and click the add button.
    4. Click Apply.

    The following image shows an example of how to configure the settings:

    Allow API access

  2. To allow access to administrative services from the zone containing the administrator's IP address, do as follows:

    1. Go to Administration > Device access. Under Admin services, select the administrator's zone for HTTPS and SSH.

      If you want to allow access from the WAN zone, we recommend that you create an exception rule limiting the access for specific services.

    2. Scroll down to Local service ACL exception rule. Click Add, and create an exception for the zone.

    3. In this example, we specify the following settings:

      Setting Description
      Source zone LAN
      Source network/host API administrator
      Destination host Port2
      Services HTTPS

      SSH
      Action Accept

    4. Click Save. The following image shows an example of how to configure the settings:

      Local service exception rule for WAN access

Get, add, update, or delete an IP host

You get, add, update, or delete an IP host using a browser's address bar.

Paste the following strings in a browser's address bar based on your requirement:

  • Get the IP hosts in the configuration:

    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Get><IPHost><Name></Name><IPFamily></IPFamily><HostType></HostType><IPAddress></IPAddress></IPHost></Get></Request>

    You see the list of configured IP hosts.

  • Add an IP host:

    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Set><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>198.1.2.1</IPAddress></IPHost></Set></Request>

    Go to Hosts and services > IP host, and see the list for the IP host Test10.

  • Update the IP address of Test10:

    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Set><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>198.1.3.3</IPAddress></IPHost></Set></Request>

  • Delete the IP host Test10:

    https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>API admin</Username><Password passwordform="encrypt">8b1e6eb1b182b1806390ffefc99753fc</Password></Login><Remove><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType><IPAddress>198.1.3.3</IPAddress></IPHost></Remove></Request>

More resources

Back to top