Getting started

Overview¶

This guide helps you use the License Management API to view configured licenses. This API can be used by both Sophos partners and customers.

Pre-requisites¶

You must be enrolled in the Sophos Partner Program to call this API as a partner. You must read the Partner Getting started guide first.

To call this API for an organization that has Sophos Fusion Enterprise access enabled, read the Organization Getting started guide.

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

The instructions in this guide assume you have authenticated using API credentials and obtained a valid JWT token ({jwt}). You should also have the UUID of the tenant account that you can pass to each API call ({tenantId}).

For tenant-level credentials, the UUID is returned by the Who-am-I API. If you are using partner-level credentials, call the Partner API to enumerate tenants and get their UUIDs. If you are using organization-level credentials, call the Organization API to enumerate tenants and get their UUIDs.

API operations¶

You can perform the following operations using the Licensing API:

Operation	HTTP Method	Path
List tenant licenses	`GET`	`/licenses/v1/licenses`
List firewall licenses	`GET`	`/licenses/v1/licenses/firewalls`

Note: The base URL for the API calls above is https://api.central.sophos.com.

List tenant licenses¶

Call this API to get a list of tenant license details:

GET /licenses/v1/licenses
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

If successful, this API returns 200 OK, and the response body looks like this:

Response:

{
  "tenant": {                              // Requested tenant ID.
    "id": "ec1baef5-a456-4e77-979a-439ad034ff6f"
  },
  "organization": {                        // Organization the tenant belongs to.
    "id": "759861d6-8ea1-4fba-b33a-0b0595d877c2"
  },
  "licenses": [                            // List of tenant licenses; may be empty.
    {
      "id": "LICENSE-ID-1234",             // Unique license ID.
      "licenseIdentifier": "LN123456789",  // License identifier.
      "product": {
        "code": "CIXA-MSP",                           // Product code.
        "name": "Central Intercept X Advanced (MSP)", // Product name.
        "genericCode": "CEP"                          // Generic product code.
      },
      "startDate": "2024-01-15",           // License start date.
      "endDate": "2026-01-14",             // Optional. License end date. Note: MSP licenses are perpetual.
      "perpetual": false,                  // `true` if `endDate` is not present or very large.
      "type": "usage",                     // License type; one of: `trial`, `term`, `usage`, `ordered`, or `enterprise`.
      "quantity": 0,                       // Note: MSP licenses don't have a quantity.
      "unlimited": true,                   // `true` if quantity is not present or 0.
      "usage": {                           // Present only if usage was ever recorded.
        "current": {
          "count": 42,                              // Usage quantity.
          "date": "2024-06-19",                     // The date for which this usage applies.
          "collectedAt": "2024-06-20T00:02:01.598Z" // The date and time at which the usage was collected.
        }
      }
    }
  ]
}

List firewall licenses¶

Call this API to get a list of firewall licenses for a tenant:

GET /licenses/v1/licenses/firewalls
Authorization: Bearer {jwt}
X-Tenant-ID: {tenantId}

To get a list of partner-owned firewall licenses, call:

GET /licenses/v1/licenses/firewalls
Authorization: Bearer {jwt}
X-Partner-ID: {partnerId}

The response is paged. You can use the following query parameters to sort the items in the response and to fetch a specific page of items.

page: Integer. Requested page number, starting with 1.
pageSize: Integer. Requested page size, defaults to 100.
pageTotal: Boolean. Set this to true if you want pages.total and pages.items populated in the response.
sort: String. The value should be {field}:{direction}, where {field} is serialNumber or lastSeenAt, and {direction} is set to asc to sort ascending or desc to sort descending.

If successful, this API returns 200 OK, and the response body looks like this:

Response:

{
  "items": [
    {
      "serialNumber": "V123456789",                     // Firewall serial number.
      "owner": {
        "id": "759861d6-8ea1-4fba-b33a-0b0595d877c2",   // Owner ID.
        "type": "organization"                          // `partner` for partner-owned firewalls.
      },
      "organization": { "id": "759861d6-8ea1-4fba-b33a-0b0595d877c2" },  // Optional. Not present for partner-owned firewalls.
      "partner": { "id": "3e22eaad-9a47-4f2d-ab1f-27e2fed12edf" },       // Optional. Present only if the firewall is managed by or associated with a partner.
      "tenant": {"id": "ec1baef5-a456-4e77-979a-439ad034ff6f"},          // Optional. Present only for organization-owned firewalls.
      "billingTenant": { "id": "ec1baef5-a456-4e77-979a-439ad034ff6f" }, // Optional. Present only for partner-managed firewalls.
      "modelType": "hardware",                          // Firewall model type. Can also be `virtual`.
      "model": "XGS136",                                // Firewall model.
      "lastSeenAt": "2024-08-12T18:59:30.043Z",         // Optional. When the firewall last fetched licenses.
      "licenses":[                                      // Always present and non-empty.
        {                                               // Base software license. Always present.
          "id": "V123456789",
          "licenseIdentifier": "LICENSE-ID-5678",
          "product": {
            "code": "XA1DTCH",                    // Product code.
            "name": "XGS136 Security Appliance",  // Product name.
            "genericCode": "XGS136"               // Generic product code.
          },
          "startDate": "2024-01-15",     // License start date.
          "endDate": "2026-01-14",       // Optional. License end date. Note: MSP licenses are perpetual.
          "perpetual": false,            // `true` if `endDate` is not present or very large.
          "type": "<trial|term|usage>",  // Always present.
          "usage": {                     // Optional. If present, the firewall has fetched the license at least once.
            "current": {
              "count": 1,                               // Usage quantity. Always `1` for firewalls.
              "date": "2024-08-12",                     // The date for which this usage applies.
              "collectedAt": "2024-08-12T18:59:30.043Z" // The date and time at which the usage was collected.
            }
          }
        },
        {
          "id": "LICENSE-ID-5678",                     // Example of a firewall software subscription license.
          "licenseIdentifier": "L0123456789",
          "product": {
            "code": "X-XS136",
            "name": "XGS 136 Xstream Protection",
            "genericProductCode": "XSP"
          },
          "startDate": "2024-02-01",
          "endDate": "2024-04-30",
          "perpetual": false,
          "type": "trial",
          "usage": {
            "current": {
              "count": 1,
              "date": "2024-08-12",
              "collectedAt": "2024-08-12T18:59:30.043Z"
            }
          }
        }
      ]
    }
  ],
  "pages": {
    "current": 1,
    "total": 1,
    "items": 1,
    "size": 100,
    "maxSize": 100
  }
}

Limitations¶

Note that, at this time, the usage object in the response to GET /licenses/v1/licenses is only returned for MSP licenses. We are working on removing this limitation and adding more features to this API.

Additional resources¶

You can download a Postman collection for this API. For details on Postman, see Postman API client. For further details on the License Management API, see the API reference.