Azure Sphere (Integrated) and Azure Sphere (Legacy)

On 27 September 2027, Azure Sphere will retire its Legacy service interfaces, Azure Sphere (Legacy) API (also known as PAPI), and Azure Sphere CLI (also known as azsphere). Users must migrate to Azure Sphere (Integrated) before this date.

Azure (Integrated) is a new service interface for Azure Sphere with many advantages over Azure Sphere (Legacy). We are retiring the Legacy interface because the Integrated interface not only provides a like-for-like replacement, but also offers significant improvements in security (Azure RBAC integration), usability (Azure Portal integration), and observability/alerting (Azure Monitor integration), as detailed below.

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).

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 resources such as VMs, IoT Hubs and devices, or Azure Active Directory (AAD) user profiles. For details about Azure Resource Manager, see the Azure Resource Manager documentation.

• 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.
• 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. This will continue to be true even after Azure Sphere (Integrated) becomes Generally Available, though we recommend that customers plan to move to Azure Sphere (Integrated) over time due to its additional features below.

We have made this change because Azure Sphere (Integrated) enables many new features for customers which are not available with the Azure Sphere (Legacy) interface:

• It includes an Azure Portal interactive user interface.
• Azure Active Directory 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).

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 PAPI 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, existing customers can continue to use the Azure Sphere (Legacy) interface as normal, while developing and testing new tooling/scripts/processes based on the Azure Sphere (Integrated) interface.

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

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 the main functionality 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 Active Directory, you may incur charges for those individual services.