Manage tenants

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

An Azure Sphere tenant provides a secure way for your organization to remotely manage its Azure Sphere devices in isolation from other customers' devices. Your organization must create an Azure Sphere tenant and then claim each of its devices into that tenant, so that you can manage those devices remotely and securely.

Prerequisites

• Install the Azure Sphere SDK for Windows or for Linux.
• You must have an unclaimed device that has not previously been used to create a tenant.

Create an Azure Sphere tenant

An Azure Sphere tenant isolates your Azure Sphere devices and provides a way for you to organize and deploy applications. The account that creates the tenant is automatically assigned the role of administrator for the tenant.

Tip

• Once a tenant is created, it cannot be deleted, and devices cannot be migrated between tenants. If your team or organization already has an Azure Sphere tenant, consider requesting access to it rather than creating an additional tenant.

To create an Azure Sphere tenant:

1. Connect an Azure Sphere device to your computer by USB.

2. Open an Azure Sphere CLI using PowerShell, Windows Command Prompt, or Linux command shell.

3. Log in to the CLI, following the instructions here.

4. To create the tenant, enter the following command:

   azsphere tenant create --name <tenant-name or tenant-ID>
   

   Replace <tenant-name> with a name that other users can recognize, such as "Contoso Ltd" or "Contoso Dishwasher Division." When you name your tenant, use only alphanumeric characters and spaces. If you include spaces, enclose the name in quotation marks. The name must not start with a space or exceed 50 characters. Special characters are not allowed. Names are case sensitive.

When you create a tenant, the Azure Sphere Security Service records the device ID of the attached device. Each device ID can be used to create only one Azure Sphere tenant.

If your account already has access to an Azure Sphere tenant, then the command will fail, advising you to use the existing tenant. If you are sure that you want to create a new tenant, you can use the --force-additional parameter to force a new Azure Sphere tenant to be created.

The azsphere tenant create command creates a tenant but does not claim the device into the tenant. For more information, see Claim your device.

To create a tenant using the API, use the Tenants - Create operation.

Show and select default tenant

Run azsphere tenant show-selected to verify that the selected tenant should be used as the default on this PC.

To modify or select the default tenant, run azsphere tenant select.

Tip

If you log out and log in again in to the Azure Sphere Security Service, you may prompted to select the default tenant. Be sure to sign in with the account that you want to use to manage your Azure Sphere devices.

List tenants

You can list the available Azure Sphere tenants using the following options:

Azure Sphere CLI

Run the following command to list the available Azure Sphere tenants.

azsphere tenant list

To list a tenant using the API, use the Tenants - Get operation.

Visual Studio Code

To list tenants in Visual Studio Code:

Select the Azure Sphere Explorer icon in Visual Studio Code's Activity Bar to open Azure Sphere Explorer.

If the Tenant pane shows Log in to see tenants, log in to Azure Sphere and select Refresh to see the available tenants.

Visual Studio

To list tenants in Visual Studio:

Select View > Other Windows > Azure Sphere Explorer to open Azure Sphere Explorer.

If the Tenant pane shows Log in to see tenants, log in to Azure Sphere and select Refresh to see the available tenants.

Update an existing tenant

You can use the Azure Sphere CLI or the Azure Sphere Public API to rename an existing Azure Sphere tenant. When naming your tenant, use alphanumeric characters. Special characters are not allowed. The name must not exceed 50 characters and is case sensitive.

To update a tenant using the CLI, run the command:

azsphere tenant update --tenant a323c263-2aa3-2559-aabb-a3fc32631900 --new-name Tenant2

Tip

A message may be displayed if the default tenant is not selected. Select the required tenant from the list and retry the command.

To update a tenant using the API, use the Tenants - Patch operation.

Download error report for tenant

To obtain error reports for all devices within a tenant, use the azsphere tenant download-error-report command.