How our APIs work

Introduction¶

Sophos Fusion's Public API program makes it easy for you to automate your monitoring, security and administration activities in Sophos Fusion. You can do many of the things that you normally would do in Sophos Fusion Admin or Sophos Fusion Partner.

Our REST APIs are available as HTTP endpoints over the public internet. They use standard authentication, JSON requests and responses, and standard HTTP verbs. All communication is over HTTPS.

This document tells you how to call APIs, covering authentication, constructing API endpoint URIs, response status codes, error handling, pagination, rate limits and so on.

REST and GraphQL APIs

The Concepts pages describe our REST APIs. GraphQL APIs share some of the same conventions, but not all of them.

For both API types, you create service principals, get authentication tokens, and pass the X-Tenant-ID header in the same way.

GraphQL APIs don't use separate regional endpoints. They also handle rate limits, errors, and pagination differently.

Each GraphQL guide contains the information you need for that API.

This page covers the partner/organization/tenant model and terminology. The mechanics of calling an API live on their own pages:

Getting started¶

You must be enrolled in the Sophos Partner Program to call our Partner APIs. You must read the Partner Getting started guide first.

To call APIs for an organization that has Sophos Fusion Enterprise access enabled, go to the Organization Getting started guide.

If neither profile fits you, read the Tenant Getting started guide.

Partners, organizations and tenants¶

To use our APIs effectively, you need to know the following terminology. We use it in all our documentation.

Partner: A partner is a business entity, typically a Distributor, a Value Added Reseller (VAR) or a Managed Service Provider (MSP) that operates within the Sophos sales channel. A partner manages multiple "tenants" and may sell Sophos software and services to multiple "organizations".
Organization: An organization is a business entity that uses Sophos software and services. An organization has one or more tenants within Sophos Fusion.
Tenant: A tenant is a collection of "resources" owned by an organization. An organization usually creates tenants for data isolation. They can also create tenants for ease of management. People that work for the organization, the devices they own, the security policies configured by an admin, and the security events generated, are all examples of resources that belong to the tenant.

Note:

Some tenants may not belong to an organization.
In our UIs and documentation, we use the term "customer" for MSP-managed tenants and "enterprise" for organizations. We also refer to tenants within an organization as "sub-estates".

See the diagram below to get an idea of how these entities relate to each other:

a diagram showing a Partner managing two tenants and an Organization managing three, each relationship labelled “manage”.

APIs¶

There are multiple APIs available under the Sophos Fusion API Program:

Partner workflows and data are available under the Partner API.
Organization workflows and data are available under the Organization API.
Tenant workflows and data are available under multiple APIs. Most of the functionality and data that is common across our products is available under the Common API. Endpoint Protection and Server Protection related functionality and data are available through the Endpoint API

Who can call which API¶

Partners can call the Partner API as well as the Tenant APIs for the tenants they manage.

Organizations can call the Organization API as well as Tenant APIs for tenants that are part of their organization.

Tenant API consumers are limited to Tenant APIs and can't call the Partner API or the Organization API.

	Partner API	Organization API	Tenant APIs (Common API, Endpoint API, and so on.)
Partner API consumers	Can call	Can call	Can call
Organization API consumers	Can't call	Can call	Can call
Tenant API consumers	Can't call	Can't call	Can call

Terminology¶

Here's a list of terms you may come across in our APIs.

Term	Definition
Partner	A partner is a business entity, typically a Distributor, a Value Added Reseller (VAR) or a Managed Service Provider (MSP) that operates within the Sophos sales channel. A partner can manage one or more tenants.
Organization	An organization is a business entity that uses Sophos software and services. An organization can own and manage one or more tenants.
Tenant	A tenant is a business entity that is also a collection of resources (people, devices, events, alerts, etc.) owned by an organization. A tenant belongs to one organization only and is managed by one organization or partner.
Account	A generic way to refer to a partner, organization or tenant.
Person	Someone who works for a partner, organization or tenant or benefits from their use of Sophos security software.
Admin	A person who can perform administrative actions on their Sophos Fusion account.
Device	A physical or virtual computing device that can be protected by Sophos security software.
Management Agent	A generic way to refer to a collection of Sophos security software components running on a device, that allow that device to be administered remotely from Sophos Fusion.
Endpoint	A device running the Sophos Enduser or Server Protection agent.
Alert	A notification generated by Sophos Fusion that requires an admin's attention.

Feedback and support¶

You can join our community support forum if you have any queries, or want to send us feedback. You can also open a Support Case. Make sure you select 'Sophos Central'. Please explain your API issue in detail. If possible, include full API requests and responses, and any relevant information such as the product version and operating system. Please don't include your API credentials or any personal information.