REST API access and API keys

Learn how to turn on API access, restrict access to trusted IP hosts, and generate API keys for authentication. Use the OpenAPI specification file and API Reference guide to create and manage firewall configurations through the Sophos Firewall REST API.

API access settings

API access is turned off by default. To use the REST API, turn it on and allow access only from trusted IP hosts. This helps ensure that only authorized administrators can access firewall configurations through the API. Administrators can then use the REST API to create, read, update, and delete firewall configurations.

To allow API access from the endpoint devices of administrators, do as follows:

1. Go to Administration > API access.
2. Turn on API access.

3. Under Allowed IP hosts, specify the IP hosts from which administrators can access the firewall through the REST API.

   The IP hosts can contain IP addresses, IP ranges, or networks. You can add up to 64 entries.

   Note

   When you upgrade to SFOS 22.0 and later, the firewall automatically converts previously configured allowed IP addresses into IP host objects. These migrated objects are named using the prefix apiconfig, for example, apiconfig_1_ajgy5q.

4. Click Apply.

REST API keys and help

Use the OpenAPI specification file and API Reference guide to understand the firewall's REST API and build API requests. Generate API keys to authenticate and authorize requests based on administrator permissions.

REST API help

Download the OpenAPI specification file to import to API clients and use the API Reference guide to understand authentication requirements, endpoint schemas, and object references.

• OpenAPI.yaml: The OpenAPI specification file for the firewall configuration API. It defines API endpoints, parameters, and request and response schemas.

  To use the file as the basis for creating API requests in clients, such as Postman or Swagger, do as follows:

  1. Click the link to download the firewall's OpenAPI.yaml file and save it to your endpoint device.
  2. Import the file to the API client.
  3. Make the required changes to attributes and values based on the schema and send REST API requests to the firewall.

• REST API guide: Click the link to see the Sophos Firewall API Reference portal.

  Learn about the base URL, authentication requirements, naming conventions, and object reference formats. The reference guide explains how to authenticate API requests, identify API objects, and correctly reference dependent objects in your configurations.

  In the left menu, select a feature and then an endpoint to view its schema.

  See Sophos Firewall API Reference.

Add API key

An API key is required to authenticate and authorize REST API requests. The key is specific to each administrator.

How API keys work

Learn about API key validity and permissions.

• Administrators can create and delete their own API keys, but all administrators can view the list of API keys.
• The firewall supports a total of 1024 API keys and 10 keys per administrator.
• The default admin can delete any administrator's keys.
• The keys are valid for one year.
• API keys inherit the permissions of the administrator account that creates them. For example, if an administrator can manage only intrusion prevention, the API keys that administrator generates can perform REST API operations only within those permissions.

Best practices

To help keep your automation secure, we recommend following best practices:

• Follow the principle of least privilege. Don't use the default admin account to generate API keys. It contains full permissions.
• Create a dedicated administrator account for API access and assign only the permissions required for managing the relevant features. Sign in with that account and generate the API key.
• Don't share API keys among administrators.

How to generate an API key

To generate an API key, do as follows:

1. Go to Administration > API access.
2. Under REST API keys, click Add API key.
3. Enter a name for the API key.

4. Click Add API key.

   The API key is generated and is valid for one year.

5. Copy the API key and store it in a secure location.

   Warning

   After you close the pop-up, the key is never shown again.

6. Click Close.

Unsupported features

The REST API supports most Sophos Firewall features in SFOS 23.0. The following table shows features that aren't currently available through the API. Support for these features will be added in future releases.