Securely automate Sophos Central Endpoint API

The Sophos Central API is suitable for recurring inventory, controlled bulk changes and integration with custom operational processes. However, it is not a second reporting interface without consequences. Depending on its role, an application can scan endpoints, change groups, edit policies, assign software, migrate devices or start Live Discover queries.

Secure automation therefore starts with three questions: Which tenant is affected, what is the smallest permission required, and how can every change be evidenced and reversed?

API Credentials as a separate identity

Under Global Settings > Access Control > API Credentials, a Super Admin creates a service principal. Its name and description identify the application, owner, purpose and expiry date. Personal administrator credentials or a Super Admin account do not belong in scripts.

Sophos provides several roles. The following are particularly relevant for Endpoint tasks:

The Client Secret is shown only once and must immediately be stored in a secret store. Sophos does not send a warning before an API Credential expires. After expiry, the entry is removed automatically and the application cannot sign in again until new credentials are created. Expiry monitoring and rotation must therefore take place outside Central.

Legacy API Tokens for the SIEM Integration API are being replaced. Existing tokens work only until they expire; new integrations use API Credentials.

Authentication and the correct API host

Sophos uses OAuth2 with the client credentials flow. The application sends its Client ID and Client Secret to the Sophos ID endpoint and receives a time-limited bearer token. Never include the token, secret or complete request headers in tickets or unprotected logs.

After signing in, query the global Who Am I endpoint first. Its response provides the tenant ID and the API host for the data region. Only then should the application call a regional endpoint such as api-eu01.central.sophos.com or api-eu02.central.sophos.com. In addition to the bearer token, the regional request requires the X-Tenant-ID header.

For a manual check, Central also displays the region under Profile > Support settings. Alternatively, it can be identified in the hostname of an installer download link. Automations must still use Who Am I, because a region read from the interface is not a reliable multi-tenant mechanism.

Important: Do not infer the region from the company’s location or language. A host hard-coded in a script may be wrong for the next tenant. Who Am I or the tenant list is the authoritative source.

Partner and Enterprise automations work with several tenants. They first determine the partner or organisation ID, read every tenant including its data region, and then make the actual request for each tenant using its regional host and tenant ID.

What the Endpoint APIs cover

The official interfaces include the ability to:

• inventory devices and trigger actions such as a scan,
• create and change Endpoint groups and assign devices,
• create, clone and prioritise additional policies and change their settings,
• assign Protection, Device Encryption or ZTNA as device software,
• query available Recommended, Fixed, LTS and Support packages,
• organise devices with key-value tags,
• control Endpoint migrations between tenants,
• read Account Health results and trigger supported remediations,
• evaluate Audit Events, alerts, XDR cases and detections,
• start saved or custom Live Discover queries.

Not every licence and role can perform every operation. Before making a write operation, use a read-only call to confirm that the tenant, object IDs, licence and expected current state match.

Some APIs have narrower limits than their names suggest. The Cases API can currently create and change only self-managed cases. Sophos also specifies a soft limit of 100 requests per tenant per 24 hours and 10 requests per user per minute. When retrieving case detections, a page size above 50 returns 400 Bad Request. The Endpoint Software API can list packages only for Windows computers and servers and currently requires the Service Principal Super Admin role. Check such API-specific prerequisites in the relevant reference before implementation instead of deriving them from general roles or limits.

Groups, tags and software assignment

Groups remain the mechanism for policy assignment. Tags complement them for inventory, search and external workflows. A tag consists of a key and an optional value. The key and value can each contain no more than 40 characters and cannot contain a colon. Each endpoint can have up to 15 tags, and the same key can have only one value on a device.

A tag or software request can contain up to 1,000 Endpoint UUIDs. For bulk operations, an HTTP 200 response does not necessarily mean that every object was changed. The application must also evaluate per-device partial failures and must not blindly repeat the entire operation.

In the Device Software API, Protection, Encryption and ZTNA are separate categories. All assigns the highest licensed variant only within the specified category; None removes only that category. Query the available software IDs for the specific endpoint. They are case-sensitive and depend on the licence and device catalogue.

Do not treat policies like text files

The Endpoint Policy API can read Base Policies and additional policies. Additional policies can be created, cloned, updated and deleted. For a Base Policy, only its settings can be changed, not its name, priority or enabled state.

Before an update, preserve the policy type, current priority, assignments and existing settings. A PATCH should contain only deliberately changed keys. Automation must not overwrite unknown settings or settings that Sophos has added since the script was written with an old complete object.

Write requests for policies have additional rate limits per tenant. Syntactically successful requests also do not prove that the change is operationally safe. As in the GUI, use a pilot group, change window, Audit Log and rollback plan.

Pagination, rate limits and retries

Lists must be read completely across every page. Depending on the interface, Sophos APIs use offset-based or key-based pagination. A script that processes only the first response page can report an incomplete inventory as complete.

Sophos specifies guideline values or limits of 10 requests per second, 100 per minute, 1,000 per hour and 200,000 per day for API use. Individual APIs may have stricter limits. Retry 429 Too Many Requests and temporary 5xx errors with exponential backoff and random jitter. An unchanged infinite loop is wrong for authentication, permission or validation errors.

Each run should log at least the tenant ID, operation, object count, successful and failed IDs, request time and a custom correlation ID. Remove secrets, bearer tokens and sensitive response content from logs.

Safe rollout process

Start new automation with a test tenant or a small pilot group. First run the same workflow in read-only mode and produce an auditable plan. Then make exactly one controlled change and verify it through the API and in Central on the device, in the effective policy and in the Audit Log.

Expand the scope only after testing partial failures, pagination, rate limits, credential expiry and rollback. Delete API Credentials after one-off projects; permanent integrations require an owner, rotation, monitoring and a documented shutdown path.

Related articles

The specific Endpoint migration between Central tenants uses its own receiving and sending workflow. The same operational principles apply to Endpoint groups and device inventory, policy order and Live Discover, regardless of whether a change is made through the GUI or API.

Frequently asked questions