Skip to content
Avanet
Sign in

Sophos Firewall REST API: secure access and API key lifecycle

Sophos Firewall

The local REST API in SFOS 23.0 lets automation read and change configuration directly on the firewall. Start with a dedicated, narrowly privileged administrator, allow only the automation host, generate a key as that account and validate a read request first. Documentation availability does not establish a GA date or availability on older firmware.

Three interfaces, three identities

  • Local REST API: A firewall administrator’s API key acts as the bearer token; permissions come from the administrator profile.
  • Local XML API: XML payloads and administrator credentials, normally sent by HTTP POST to APIController. XML <Get> is not a REST request.
  • Sophos Central configuration API: A cloud service principal, short-lived access token, tenant and regional API host. A local firewall key does not replace these credentials.

Prepare access and the administrator

  1. Under Profiles > Device access, create a profile with only the required feature permissions; inventory-only jobs need appropriate read permissions. Under Authentication > Users, create a dedicated administrator with this profile. Administrator and profile planning explains role selection. Do not use a personal account or the fully privileged default admin for jobs.
  2. Under Hosts and services > IP host, define the actual automation host, for example api-inventory at 192.0.2.20. Replace the name and documentation address with your values. A single fixed source is narrower than an entire management network; with NAT, use the source seen by the firewall.
  3. Under Administration > API access, turn on API access, which is off by default, select only required sources under Allowed IP hosts, and click Apply. Addresses, ranges and networks are supported, with at most 64 entries. Review apiconfig sources migrated during upgrades to SFOS 22.0 or later.
  4. Under Administration > Device access, check WebAdmin access from the relevant zone. Device Access and the API source list are separate controls; do not open WAN access broadly.

Generate and capture the key once

Sign in as the dedicated administrator. Under Administration > API access > REST API keys, click Add API key, enter a descriptive name such as inventory-prod-2026-10, and generate it with Add API key.

Before Close: Copy the key into the job’s protected secret store. Once the pop-up closes, the key is never displayed again. Do not include it in screenshots, tickets, repository files or unprotected collection exports.

A key is valid for one year and inherits its creator’s permissions. Administrators can create and delete their own keys; all administrators can view the key list, not retrieve the secret again. The default admin can also delete other administrators’ keys. Limits: 10 keys per administrator, 1024 in total. Do not share keys between administrators.

Build the request from the firewall schema

Under REST API help, download this firewall’s OpenAPI.yaml and import it into Postman or Swagger. Under REST API guide, check authentication, object references and the selected endpoint’s schema. Endpoint names resemble the UI but are not always identical.

SFOS 23.0, as of 29 October 2026: The generated API reference specifies https://<firewall-host>:<port>/api/firewall-config/v1 as the base. The general introduction instead gives a path without /api and even shows APIController for the first call. This is not a reliable instruction to try different paths. For the actual firewall, use the complete server URL in its downloaded schema; do not run the following pilot without a matching local operation.

First read-only call: query applied hotfixes

The official GET /system/security-updates operation reads applied hotfix security updates. It starts neither an update nor a configuration change. Before the call, check that the local schema contains this exact path with method GET and use its complete base URL.

The example runs with Python 3 on the approved administration or automation host, not in the Device Console. firewall.example.com, port 4444 and the CA-file path are placeholders. The hostname must match the certificate; 4444 is simply the HTTPS admin port chosen for this example. The PEM file contains the trusted issuing CA, not private key material. If the certificate chain is already trusted by Python’s trust store, ca_file = None can be used. Do not trust an arbitrary downloaded CA.

python3 - <<'PY'
import getpass
import json
import ssl
import urllib.error
import urllib.request

# Vollständige servers-URL des lokalen Schemas übernehmen.
# Dieser Beispielpfad entspricht der generierten Referenz.
api_base = "https://firewall.example.com:4444/api/firewall-config/v1"
ca_file = "/pfad/zur/management-ca.pem"
if not api_base.startswith("https://"):
    raise SystemExit("Nur die bestätigte HTTPS-Server-URL verwenden.")
context = ssl.create_default_context(cafile=ca_file)

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(
    NoRedirect(), urllib.request.HTTPSHandler(context=context)
)
api_key = getpass.getpass("Freigegebener REST-API-Schlüssel: ")
request = urllib.request.Request(
    api_base.rstrip("/") + "/system/security-updates",
    method="GET",
    headers={
        "Accept": "application/json",
        "Authorization": "Bearer " + api_key,
    },
)
try:
    with opener.open(request, timeout=30) as response:
        status = response.status
        body = response.read()
except urllib.error.HTTPError as error:
    raise SystemExit(f"HTTP {error.code}: Ursache vor erneutem Aufruf prüfen.")
except urllib.error.URLError as error:
    raise SystemExit(f"Verbindungs- oder TLS-Fehler: {error.reason}")

print(f"HTTP {status}")
if status != 200 or not body:
    raise SystemExit("Noch keine Abnahme: Status und Body mit dem Schema abgleichen.")
try:
    data = json.loads(body)
except (json.JSONDecodeError, UnicodeDecodeError):
    raise SystemExit("Kein gültiger JSON-Body; Zielpfad und Antwort prüfen.")
print(json.dumps(data, indent=2, ensure_ascii=False))
PY

The key is entered without being displayed, rather than stored as a command argument or a literal in the script. The client accepts only HTTPS and follows no redirects: it stops at an unexpected 3xx response rather than forwarding the Bearer header to another destination. Do not enable shell/client debug logging during the pilot; the returned device data must not be copied unchecked into tickets either. For an unattended job, use the designated secret store later.

Interpret the response and common errors

A successful request returns HTTP 200. The data should describe applied hotfix security updates. Compare the count and content with the known device state and this firmware’s response schema; valid JSON alone proves neither completeness nor a particular patch level.

  • 401: The reference requires authentication. Check the Bearer header, correct key, expiry and deletion without logging the secret.
  • 403: The reference requires permission. Check the creator account and its rights for the operation rather than granting full administrator permissions indiscriminately.
  • 3xx: Do not redirect. Check the confirmed server URL, any upstream proxy and its redirect rules; do not pass the key to the redirect destination.
  • 404: A 404 is not documented as an operation-specific response. Check the admin port, full schema base, path, firmware and any upstream proxy. Do not automatically switch to the XML endpoint or a second REST prefix.
  • 400 or 500: The reference distinguishes an invalid request from an internal server error. Check method and schema, or device state and sanitised diagnostics, as appropriate.
  • No HTTP status: Investigate DNS, routing, connection, timeout and the TLS certificate chain. For certificate errors, correct the hostname, chain of trust and validity; do not disable verification with -k or an unverified SSL context.

Read test and operational validation

First accept the allowed path from the real automation host. For the source negative test, send the same read-only request only from an additional approved test host already outside the API source list. It must not receive configuration or hotfix data. No particular rejection status is guaranteed; a response containing data would fail the negative test. Do not remove production access or use an unrelated network for this test.

The TLS negative check also preserves protection: an explicitly approved test hostname deliberately not matching the certificate must fail certificate verification before API data is received. Do not change production DNS or add network access to arrange this. Without a suitable test name, this part of acceptance remains open. Record time, source host, firmware, schema version, HTTP/TLS result and substantive data comparison, never the key.

Before writes, prepare a backup and recovery path, test one small approved change, and inspect the target in WebAdmin and the Audit Trail. After a write timeout, read the actual object state before retrying. Slow queries, such as IPS signatures, may need longer client timeouts.

Expiry, replacement and deletion

Record each key’s account, job, allowed source, creation date, expiry date and responsible team, never the key itself. Schedule reminders and replacement before expiry; do not assume automatic renewal. Reserve a free key slot for overlapping rotation. At 10 own keys or 1024 total, identify unneeded keys with their owner first rather than revoking active jobs indiscriminately.

For planned replacement, generate and capture a new key under the same account, switch the job and validate a read. Only then delete the old key you own and check that the new one works and the old one no longer grants access. Do not treat deleted keys as recoverable. Replace a key if its one-time display was lost. Suspected exposure takes priority over uninterrupted rotation: revoke immediately. Involve the default admin owner to delete another administrator’s key. On decommissioning, delete keys and remove unneeded API sources, checking shared sources first.

SFOS 23.0 boundaries

The current feature scope excludes these functions from this REST API:

  • Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
  • All Email, Wireless and RED features.
  • Network: DDNS and IP tunnels; SD-WAN profiles.
  • VPN: IPsec routes, GRE routes, L2TP, PPTP, SSL VPN site-to-site clients and servers.
  • Authentication: Guest users and clientless users; Firewall rule groups.
  • Let’s Encrypt certificates; High availability and TAP mode; System time.
  • Status information, for example DHCP leases, HA status and data storage.

The list is not exhaustive or a promise for a future release. Check every required operation against the current schema; a visible UI menu does not establish API support. XML or cloud access is not an automatically equivalent substitute.

When a job fails

For connection failures, check the post-NAT source, routing, admin port, TLS, API access and Device Access. For authentication or permission failures, check the correct key, expiry, deletion, creator account and profile rather than granting full rights. For schema errors, compare method, path, required fields and dependent object references. Resolve a lost key by replacement, not by looking for another display.

For escalation, retain firmware, schema version, timestamp, endpoint, HTTP status and a sanitized response, without secrets. Sophos supports the official REST API and unmodified scripts, not advice or troubleshooting for custom integrations. Those require an internal owner; involve a partner or Sophos Professional Services if needed.