Authentication

Authorization¶

The service principal must have the right set of permissions to make an API call. While our APIs are in Preview, a service principal will have access to limited functionality, but all access is at the SuperAdmin level.

Multi-tenancy header: X-Tenant-ID, X-Partner-ID, X-Organization-ID¶

Each partner, organization and tenant entity has a Universally Unique ID (UUID) assigned to it in Sophos Central. All APIs but one require you to pass in this UUID as a request header.

Once a principal has authenticated, they can find the partner, organization or tenant UUID from their security context by calling the following API:

GET https://api.central.sophos.com/whoami/v1

This "Who Am I?" API doesn't require passing an X-*-ID header. The response varies depending upon the calling principal.

For an authenticated partner principal, it looks like:

{
    "id": "5AC55058-622D-4929-8E5D-8FF554F312FE",
    "idType": "partner",
    "apiHosts": {
        "global": "https://api.central.sophos.com"
    }
}

Here, the id is the partner's UUID.

For an authenticated organization principal, it looks like:

{
    "id": "C37A4BC7-715A-48FD-AE03-D184A391B136",
    "idType": "organization",
    "apiHosts": {
        "global": "https://api.central.sophos.com"
    }
}

The id is the UUID of the organization to which the principal belongs.

For an authenticated tenant principal, the response looks like:

{
    "id": "7E29B4C2-E68A-4617-BFE1-844666B5300F",
    "idType": "tenant",
    "apiHosts": {
        "global": "https://api.central.sophos.com",
        "dataRegion": "https://api-us02.central.sophos.com"
    }
}

The id is that of the tenant to which the principal belongs.

To call the tenant Common API to fetch alerts, the caller should use the id and dataRegion values from the response above:

GET https://api-us02.central.sophos.com/common/v1/alerts

... passing the required headers:

X-Tenant-ID: 7E29B4C2-E68A-4617-BFE1-844666B5300F
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0
                      NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M
                      DIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The header has been split across multiple lines and indented for legibility.