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

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

Note

Note that Azure Sphere (Legacy) does not support new Azure Sphere (Integrated) features, such as Azure Monitor integration and Azure Role Based Access Control (RBAC).

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.