API
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. 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. 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. 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 configuration request. Here are the details of these components:
| Component | Description |
|---|---|
| API controller string |
|
| 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>"
Examples
Get request:
https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>xyz123
</Password></Login><Get><IPHost/></Get></Request>
Set request:
https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>xyz123
</Password></Login><Set><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType>
<IPAddress>198.1.2.1</IPAddress></IPHost></Set></Request>
Remove request:
https://1.1.1.1:4444/webconsole/APIController?reqxml=<Request><Login><Username>admin</Username><Password>xyz123
</Password></Login><Remove><IPHost><Name>Test10</Name><IPFamily>IPv4</IPFamily><HostType>IP</HostType>
<IPAddress>198.1.2.1</IPAddress></IPHost></Remove></Request>
XML tags and attributes
For the attributes and status codes in the following table, see API help.
| XML tags | Description |
|---|---|
<Request> | Used for sending the XML request. Attribute: Example: |
<Login> | Authenticates the administrator. Example: |
<Username> | Administrator's username. Example: |
<Password> | Administrator's password. Example: You can use a plaintext password or an encrypted password. The encrypted password is in the 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. Example: |
<Set> | Adds or updates based on the tag you specify. For the attributes, see API help. Example: 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. Example: |
<Filter> <Key> | Filter gets data for the criteria you specify in the tag Use Example: |
<Response> | Response for your request. Attribute: Attribute value: The response tag shows the active firmware API version. Configuration tags show the value you specified in the XML request. Example: |
<transactionid> | Transaction ID you enter in the request. You can set the transaction ID for any type of request, for example, Get, Set, Remove. Attribute: Attribute value: You can enter any value, for example, letters, numbers, and special characters. Example: |
<Status> | Configuration status based on the code. Attribute: Attribute value: Code number Example: 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:
- Download the API help.
- 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.
- 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.
<Request><LiveUserLogin><UserName>sophos</UserName><Password>sophos</Password><IPAddress>10.21.18.15</IPAddress>
<MacAddress>00:0C:29:2D:D3:AC</MacAddress> </LiveUserLogin></Request>
<Request><LiveUserLogout><Admin><UserName>admin</UserName><Password>admin</Password></Admin><UserName>sophos</UserName>
<IPAddress>10.21.18.15</IPAddress></LiveUserLogout></Request>
Example
https://<Sophos Firewall IP address>:4444/webconsole/APIController?reqxml=<Request><LiveUserLogin><UserName>sophos
</UserName><Password>sophos</Password><IPAddress>10.21.18.15</IPAddress><MacAddress>00:0C:29:2D:D3:AC</MacAddress>
</LiveUserLogin></Request>
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