Getting started as a Tenant¶

This guide takes you through a few simple steps to get authenticated and start calling Sophos Fusion APIs.

At the end of this guide, you will have:

1. Created a "service principal" for your "tenant"
2. Authenticated using your new credentials
3. Discovered the UUID assigned to you by Sophos
4. Retrieved the list of endpoints

A "service principal" is a set of credentials that can be used to authenticate and call APIs.

A "tenant" is a collection of resources such as devices, events, policies and people. You can read more about this in the documentation under the "Partners, organizations and tenants" section.

Step 1 - Create a service principal¶

We will show you how you can sign in to Sophos Fusion Admin and create a service principal. You need to have the Super Admin role to do this.

Step 1a - Sophos Fusion Admin¶

Sign in to Sophos Fusion Admin. Go to https://central.sophos.com/manage.

Click 'Global Settings' and then click the "API Credentials" link.

Step 1b - Add a new set of credentials¶

Supply a name for your credential set and a description, then click 'Add'.

Note: To delete these credentials later, after you no longer need them, click on the entry in the credentials list to open the details view, then click 'Delete'. Next, click 'Delete' in the popup dialog to confirm deletion.

Step 1c - Grab your client ID and secret¶

Click 'Copy' to note down the client ID. Also show the client secret.

Click 'Copy' to note down the client secret.

⚠️ WARNING: It is your responsibility to store your client ID and secret securely. If these are lost or stolen, an attacker will be able to call APIs on your behalf and steal your data or cause damage.

Now you are ready to start calling APIs.

Step 2 - Authenticate¶

You can make API calls in the next few sections using cURL. Follow the instructions on cURL's website to install this tool.

Note: Some command lines in the examples below have been split over multiple lines for legibility. Remove the \ before running the commands. Also replace curl with curl.exe on Windows.

From a command line prompt, run the following command, replacing <client-id> with the client_id from the previous step, and <client-secret> with the client_secret from the previous step:

curl -XPOST -H "Content-Type:application/x-www-form-urlencoded" \
            -d "grant_type=client_credentials&client_id=<client-id>&client_secret=<client-secret>&scope=token" \
                   https://id.sophos.com/api/v2/oauth2/token

This command returns an API response like this:

{
  "access_token": "<jwt>",
  "errorCode": "success",
  "expires_in": 3600,
  "message": "OK",
  "refresh_token": "<token>",
  "token_type": "bearer",
  "trackingId": "<uuid>"
}

Note the <jwt> token in the call above as you will need to pass it as a header in every subsequent API call.

Step 3 - Find your Tenant ID¶

After authenticating, you need to discover the ID assigned to your business entity by Sophos:

curl -XGET -H "Authorization: Bearer <jwt>" https://api.central.sophos.com/whoami/v1

A successful response looks like this:

{
    "id": "57ca9a6b-885f-4e36-95ec-290548c26059",
    "idType": "tenant",
    "apiHosts": {
        "global": "https://api.central.sophos.com",
        "dataRegion": "https://api-us03.central.sophos.com"
    }
}

Note the id in the response above. This is the "multi-tenancy" header that you need to pass in for all subsequent API calls (<tenant-id> placeholder in the rest of this document).

The dataRegion field in apiHosts in the response above is the URL you need to use in place of <data-region> for every subsequent API call.

Step 4 - List endpoints¶

Next call the following API to find all the endpoints in your tenant.

curl -XGET -H "Authorization: Bearer <jwt>" \
           -H "X-Tenant-ID: <tenant-id>" \
                <data-region>/endpoint/v1/endpoints

A successful response (when you have over 50 endpoints) looks like this:

{
    "pages": {
        "fromKey": "<from-key>",
        "nextKey": "<next-key>",
        "size": 50,
        "maxSize": 100
    },
    "items": [
        {
            "id": "4f725e46-a174-45a7-a352-49ed15840ab1",
            "type": "computer",
            "tenant": {
                "id": "2a591e9c-5a0b-4623-9e78-f28692a1616f"
            },
            "hostname": "DESKTOP-F82003",
            "health": {
                "overall": "good",
                "threats": {
                    "status": "good"
                },
                "services": {
                    "status": "bad",
                    "serviceDetails": [
                        {
                            "name": "HitmanPro.Alert service",
                            "status": "stopped"
                        },
                        {
                            "name": "Sophos Anti-Virus",
                            "status": "running"
                        },
                        {
                            "name": "Sophos Anti-Virus Status Reporter",
                            "status": "running"
                        },

                        // Other Sophos agent services
                    ]
                }
            },
            "os": {
                "isServer": false,
                "platform": "windows",
                "name": "Windows 10 Pro",
                "majorVersion": 10,
                "minorVersion": 0,
                "build": 17134
            },
            "ipv4Addresses": [
                "10.10.10.100"
            ],
            "ipv6Addresses": [
                "fe80::9f3e:aeff:8892:0bb8"
            ],
            "macAddresses": [
                "00:0B:FF:E1:C2:C2"
            ],
            "associatedPerson": {
                "viaLogin": "DESKTOP-F82003\\admin"
            },
            "assignedProducts": [
                {
                    "code": "endpointProtection",
                    "version": "10.8.3.441"
                },
                {
                    "code": "deviceEncryption",
                    "version": "1.4.103"
                },
                {
                    "code": "interceptX",
                    "version": "2.0.14"
                },
                {
                    "code": "coreAgent",
                    "version": "2.4.0"
                }
            ],
            "lastSeenAt": "2019-08-29T10:20:29.375Z"
        }
        // 49 other endpoint objects ...
    ]
}

This API uses a "key based" pagination technique rather than using page numbers.

The <from-key> example value in the pages field in the response above is the key associated with the first item on the page.

The <next-key> example value in the pages field in the response is the key you should use to fetch the next page.

Here is the API call to fetch the next 50 (or fewer) items:

curl -XGET -H "Authorization: <jwt>" \
           -H "X-Tenant-ID: <tenant-id>" \
              <data-region>/endpoint/v1/endpoints?pageFromKey=<next-key>

The response from this API shows the value to use for pageFromKey to fetch the third page (if there is one). If the nextKey value is missing, you have reached the end of pages and can stop iterating.

Conclusion¶

You can now make simple API calls. There are some things you need to know about error handling, pagination, partial responses and other aspects of calling RESTful APIs that are specific to Sophos APIs. You can read about them here.