Skip to content
Avanet

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 the base URL, authentication, object references and selected endpoint’s schema. Endpoint names resemble the UI but are not always identical.

The reference specifies this base and header; take the actual request’s path, method and parameters from the matching schema:

https://<firewall-host>:<port>/firewall-config/v1
Authorization: Bearer <API_KEY>

Replace the hostname and HTTPS admin port; insert the key using the client’s secret facility. Validate the TLS certificate and hostname rather than bypassing checks with -k. The introductory reference also contains examples using the XML APIController path; do not copy these unchecked as REST instructions. If the firewall schema has no matching endpoint, do not guess a path.

Read test and operational validation

Send a harmless, schema-compliant read request from the real automation host. Check the response and expected object data, not just HTTP success. Repeat it from a controlled source that is not allowed: it must not return configuration. Do not remove production allow entries to arrange this test.

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.