Sophos Firewall API Reference

Programmatically manage and automate every aspect of your firewall, including rules, zones, authentication, routing, and threat protection, using the Sophos Firewall REST API.

The reference is rendered from the official OpenAPI 3.0 specification for the firewall appliance configuration.

Browse the API reference →

Getting started

Learn how to securely and efficiently manage and automate configurations in Sophos Firewall using its REST API.

1. Allow API access from trusted endpoints

You must allow API access from trusted endpoints and zones.

1. Go to Administration › API access and allow access from the administrators' endpoint IP addresses or subnets.
2. Go to Administration › Device access and make sure administrators' zones have access to the web admin console.

2. Set up authentication and authorization

The firewall uses token-based authentication with API keys. All firewall administrators can access the firewall using the API. Authorization is based on the administrator profile.

1. Go to Profiles › Device access and add administrator profiles with the required permissions.
2. Go to Authentication › Users and assign the correct profile to each administrator.

note

Each administrator can go to Administration › API access and generate an API key. The keys are automatically associated with the administrator's profile.

3. Manage API keys

Custom and super administrators can create an API key for themselves. Only the super administrator can also revoke an API key for any admin user by deleting that key.

warning

Treat API keys like passwords. Never commit them to source control, rotate them periodically, and revoke any keys that may have been exposed.

4. API key permissions

The permissions of an API key are inherited from the user account that created it. For example, if a user only has permission to manage certain firewall features, the API key created by that user will have the same level of access.

As a best practice, don't use your personal administrator account for automation. Instead, create a dedicated API user, assign only the permissions required for the automation, and generate the API key from that account. This follows the principle of least privilege and helps keep your automation secure.

Base URL and authentication

All calls go to your firewall's admin endpoint:

https://<firewall-host>:<port>/firewall-config/v1

Replace <firewall-host> with the IP or hostname of your firewall and <port> with your firewall's HTTPS admin port.

Every request must include your API key in the Authorization header:

Authorization: Bearer <your-api-key>

Make your first request

curl -X GET "https://firewall.example.com:4444/webconsole/APIController" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

response = requests.get(
    "https://firewall.example.com:4444/webconsole/APIController",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    verify=True,
)
response.raise_for_status()
print(response.json())

const response = await fetch(
  "https://firewall.example.com:4444/webconsole/APIController",
  {
    method: "GET",
    headers: {
      Accept: "application/json",
      Authorization: "Bearer YOUR_API_KEY",
    },
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());

note

Some endpoints take noticeably longer to respond than others — large collections, operations that touch many objects, and calls that require the firewall to reload configuration can all take a while on a busy appliance.

Configure a generous request timeout in your API client rather than relying on its default, which is often only a few seconds. The examples above use each client's default timeout for brevity; in production, set an explicit one.

A timeout means the response never arrived — not that the request failed. Read requests (GET) are safe to retry as-is. For requests that change configuration, do not retry blindly: the firewall may have already applied the change. Re-query the affected object to establish its actual state first, then retry only if the change did not take effect.

Next steps

• Browse the API reference for every endpoint on the current firmware, with request/response schemas and code samples.
• Visit the Sophos Developer Portal for guides and SDKs across the wider Sophos product family.