Skip to content

Page permalink

Always use the following permalink when referencing this page. It will remain unchanged in future help versions.

https://docs.sophos.com/nsg/sophos-firewall/18.5/Help/en-us/webhelp/onlinehelp/index.html?contextId=API

API

You can add, update, or delete the firewall configuration using the Application Programming Interface (API).

You can use the API to apply the same configuration to multiple firewalls. The API client can be a browser, the firewall or the administrator endpoint's Linux command-line interface, or an API application, such as Postman.

API configuration

API access is turned off by default. You must turn it on and allow access to specific IP addresses.

Allow API calls from administrators' endpoints

To allow API calls from your endpoint, do as follows:

  1. Go to Backup and firmware > API.

  2. Select API configuration.

    It allows you to get, set, or remove the configuration using the API.

  3. For Allowed IP address, enter your IP address.

    You can only make changes from these sources. To get the IP address from which you access the web admin console, do as follows:

    1. Go to Log viewer and select Admin from the list.
    2. See the source IP address for your sign-in.

Note

To provide strict permissions that only allow access to specific administrators, see Allow API access to administrators.

Make an authentication request

The firewall authenticates administrators' API requests based on their credentials in the firewall.

The API client sends the credentials over HTTPS to the firewall to ensure security. HTTPS provides a secure channel between the client and server, encrypting the data in transit and ensuring that unauthorized actors don't intercept or modify the communication.

We recommend that you first verify that the port, IP address, and credentials work. You can use any of the following mechanisms to test the connectivity and credentials.

In the Postman application, enter your credentials as follows:

  1. Under Collections, click the plus button to create a new collection.

    Add a new Postman collection

  2. Under the collection, click Add a request.

    Add a new request to the collection

  3. Under New Request, use the following syntax to enter your firewall details:

    https://<firewall's IP address>:<firewall's port>/webconsole/APIController

    Post request in Postman

  4. Click Body and click form-data.

    Postman body and form data

  5. Under Key, enter reqxml.

  6. Under Value, use the following syntax to enter your credentials.

    <Request>
    <Login>
        <Username><your username></Username>
        <Password><your password></Password>
    </Login>
</Request>

    Enter the authentication request

  7. Click Send.

On the command-line of your Linux endpoint or the firewall, use the following syntax to enter your credentials:

curl -k "https://<firewall's IP address>:<firewall's port>/webconsole/APIController?reqxml=<Request><Login><Username><your username></Username><Password><your password></Password></Login></Request>"

You'll get the following response: Authentication successful.

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.

<Request><LiveUserLogin><UserName>admin</UserName><Password>abcd</Password><IPAddress>10.21.18.15</IPAddress><MacAddress>00:0C:29:2D:D3:AC</MacAddress></LiveUserLogin></Request>

<Request><LiveUserLogout><Admin><UserName>admin</UserName><Password>abcd</Password></Admin><UserName>sophos</UserName><IPAddress>10.21.18.15</IPAddress></LiveUserLogout></Request>
Example 
https://<Sophos Firewall IP address>:4444/webconsole/APIController?SecureStorageMasterKey=Passw0rd@12345&reqxml=<Request><LiveUserLogin><UserName>admin</UserName><Password>abcd</Password><IPAddress>10.21.18.15</IPAddress><MacAddress>00:0C:29:2D:D3:AC</MacAddress></LiveUserLogin></Request>

More resources