Manage tenants

  • Article

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 a Azure Sphere CLI using PowerShell, Windows Command Prompt, or Linux command shell and 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.

You can use the --force-additional parameter to force a new Azure Sphere tenant to be created. Use this command only if you are certain that you want to use the current account to create a new Azure Sphere tenant using the attached device. A device that has previously been used to create an Azure Sphere tenant cannot be used to create a new tenant.

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.