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:
Connect an Azure Sphere device to your computer by USB.
Open an Azure Sphere CLI using PowerShell, Windows Command Prompt, or Linux command shell.
Log in to the CLI, following the instructions here.
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:
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.
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.