Azure Sphere (Integrated) vs Azure Sphere (Legacy)

When Azure Sphere became generally available in 2020, a REST interface to remotely manage devices and software deployments known as the Azure Sphere Public API (PAPI) was provided. PAPI is not integrated natively into Azure services, it is a standalone REST API. The "azsphere" command line tool uses PAPI for cloud-facing commands. To integrate natively into Azure means integration with Azure Resource Manager, which is the management layer for Azure that enables you to create, update, and delete Azure-managed resources such as virtual machines or Azure IoT resources. For details about Azure Resource Manager, see the Azure Resource Manager documentation.

As of March 2024, Azure Sphere has a generally available Azure Resource Manager interface, known as Azure Sphere (Integrated), and we now refer to the PAPI based interface as Azure Sphere (Legacy).

  • Azure Sphere (Integrated)
    • Refers to the Azure Resource Manager interface for Azure Sphere, accessed through the Azure Portal, Azure CLI extension (az sphere) and Azure Sphere Security Service REST API.
    • Is generally available and fully supported.
    • Uses the same user authentication (Microsoft Entra ID) and authorisation (Azure RBAC) mechanisms as other Azure resources, enabling fine-grained access control to specific resources.
    • Is recommended for all use cases - including managing devices deployed in production solutions, and development of new solutions.
  • Azure Sphere (Legacy)
    • Refers to the original Public API (PAPI) interface, accessed through the azsphere CLI tool, and directly via the Public PAPI.
    • Remains generally available and fully supported.
    • Uses a custom user authorisation mechanism with only tenant-wide Administrator, Contributor and Reader permissions supported.
    • Is not recommended for new designs, and for current solutions we recommend that users migrate to Azure Sphere (Integrated) for all production and development workloads.

We have made this change because Azure Sphere (Integrated) enables many new features and security improvements which are not available with the Azure Sphere (Legacy) interface, including:

  • It includes an Azure Portal interactive user interface.
  • Microsoft Entra IDs can be used for fine-grained role-based access control (RBAC), for example enabling "test" and "production" device groups to have different access restrictions for deploying new software to them.
  • Azure Monitor integration enables visualization of device status and history, easier diagnosis of issues, and alerting.
  • ARM templates enable automation of Azure Sphere deployments.

Azure Sphere (Legacy) tenants and Azure Sphere (Integrated) catalogs

An "Azure Sphere tenant" is a logical grouping of Azure Sphere resources within the legacy PAPI interface - including products, devices, device groups, and software images. Since the name 'tenant' is already in use within Azure, to avoid ambiguity we are using a different word - 'catalog' - for the same logical grouping in Azure Sphere (Integrated).

Easy migration process

Existing Azure Sphere (Legacy) tenants can be integrated into an Azure Sphere (Integrated) catalog while still being accessible via the Legacy PAPI-based interfaces. This causes a new catalog to be created that relates to the same devices that are present in the Legacy tenant. It’s important to understand that the underlying Azure Sphere resources themselves (products, devices, device groups, and images) are not changed, duplicated, or deleted in this process. Because both interfaces can be used at the same time, you can continue to use the Azure Sphere (Legacy) interface for production processes, while developing and testing new tooling, scripts and processes based on the Azure Sphere (Integrated) interface, until you are ready to fully move over to Azure Sphere (Integrated). No point-in-time migration is required.

The following diagram illustrates this relationship and highlights which tools/APIs you can use to access each interface.


Note that Azure Sphere (Legacy) will not support new Azure Sphere (Integrated) features such as the Microsoft Entra ID integration that enables fine grain role-based access control.

Diagram showing that you can manage the same Azure Sphere resources via either Legacy or Integrated tools/APIs.

Getting Started

To get started developing using an Azure Sphere developer kit, follow this quickstart guidance for Azure Sphere (Legacy) or Azure Sphere (Integrated).

You can use both Azure Sphere (Legacy) and Azure Sphere (Integrated) simultaneously; the tooling installs side-by-side.

With Azure Sphere (Integrated), you can also try out the Azure Portal experience directly by going to Azure Portal and in the top search bar search for Azure Sphere. However, unless you have an Azure Sphere developer kit, you will not be able to test functionalities of Azure Sphere such as over-the-air updates or device monitoring.

Pricing Model

There is no pricing difference between Azure Sphere (Legacy) and Azure Sphere (Integrated) as the security service element (built into the chip price) covers both interfaces. When you use other Azure services enabled by this integration, such as Azure IoT Hub or Azure RBAC, you may incur charges for those individual services.