Set up an Azure Digital Twins instance and authentication (CLI)

This article covers the steps to set up a new Azure Digital Twins instance, including creating the instance and setting up authentication. After completing this article, you'll have an Azure Digital Twins instance ready to start programming against.

This version of this article goes through these steps manually, one by one, using the CLI. Setup can also be completed by using the following alternate instructions:

Full setup for a new Azure Digital Twins instance consists of two parts:

  1. Creating the instance
  2. Setting up user access permissions: Azure users need to have the Azure Digital Twins Data Owner role on the Azure Digital Twins instance to be able to manage it and its data. In this step, you as an Owner/administrator of the Azure subscription will assign this role to the person who will be managing your Azure Digital Twins instance. This may be yourself or someone else in your organization.


To complete this full article and completely set up a usable instance, you need permissions to manage both resources and user access on the Azure subscription. The first step can be completed by anyone who's able to create resources on the subscription, but the second step requires user access management permissions (or the cooperation of someone with these permissions). You can read more about this in the Prerequisites: Required permissions section for the user access permission step.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

Set up Cloud Shell session

To start working with Azure Digital Twins in an open Azure Cloud Shell window, the first thing to do is log in and set the shell context to your subscription for this session. Run these commands in your Cloud Shell:

az login
az account set --subscription "<your-Azure-subscription-ID>"


You can also use your subscription name instead of the ID in the command above.

If this is the first time you've used this subscription with Azure Digital Twins, run this command to register with the Azure Digital Twins namespace. (If you're not sure, it's ok to run it again even if you've done it sometime in the past.)

az provider register --namespace 'Microsoft.DigitalTwins'

Next you'll add the Microsoft Azure IoT Extension for Azure CLI to your Cloud Shell, to enable commands for interacting with Azure Digital Twins and other IoT services. Run this command to make sure you have the latest version of the extension:

az extension add --upgrade --name azure-iot

Now you are ready to work with Azure Digital Twins in the Cloud Shell.

You can verify this by running az dt --help at any time to see a list of the top-level Azure Digital Twins commands that are available.

Create the Azure Digital Twins instance

In this section, you'll create a new instance of Azure Digital Twins using the Cloud Shell command. You'll need to provide:

  • A resource group where the instance will be deployed. If you don't already have an existing resource group in mind, you can create one now with this command:
    az group create --location <region> --name <name-for-your-resource-group>
  • A region for the deployment. To see what regions support Azure Digital Twins, visit Azure products available by region.
  • A name for your instance. If your subscription has another Azure Digital Twins instance in the region that's already using the specified name, you'll be asked to pick a different name.

Use these values in the following az dt command to create the instance:

az dt create --dt-name <name-for-your-Azure-Digital-Twins-instance> --resource-group <your-resource-group> --location <region>

Verify success and collect important values

If the instance was created successfully, the result in Cloud Shell looks something like this, outputting information about the resource you've created:

Screenshot of the Cloud Shell window with successful creation of a resource group and Azure Digital Twins instance in the Azure portal.

Note the Azure Digital Twins instance's hostName, name, and resourceGroup from the output. These values are all important and you may need to use them as you continue working with your Azure Digital Twins instance, to set up authentication and related Azure resources. If other users will be programming against the instance, you should share these values with them.


You can see these properties, along with all the properties of your instance, at any time by running az dt show --dt-name <your-Azure-Digital-Twins-instance>.

You now have an Azure Digital Twins instance ready to go. Next, you'll give the appropriate Azure user permissions to manage it.

Set up user access permissions

Azure Digital Twins uses Azure Active Directory (Azure AD) for role-based access control (RBAC). This means that before a user can make data plane calls to your Azure Digital Twins instance, that user needs to be assigned a role with appropriate permissions for it.

For Azure Digital Twins, this role is Azure Digital Twins Data Owner. You can read more about roles and security in Security for Azure Digital Twins solutions.


This role is different from the Azure AD Owner role, which can also be assigned at the scope of the Azure Digital Twins instance. These are two distinct management roles, and Owner does not grant access to data plane features that are granted with Azure Digital Twins Data Owner.

This section will show you how to create a role assignment for a user in your Azure Digital Twins instance, using that user's email in the Azure AD tenant on your Azure subscription. Depending on your role in your organization, you might set up this permission for yourself, or set it up on behalf of someone else who will be managing the Azure Digital Twins instance.

Prerequisites: Permission requirements

To be able to complete all the following steps, you need to have a role in your subscription that has the following permissions:

  • Create and manage Azure resources
  • Manage user access to Azure resources (including granting and delegating permissions)

Common roles that meet this requirement are Owner, Account admin, or the combination of User Access Administrator and Contributor. For a complete explanation of roles and permissions, including what permissions are included with other roles, visit Classic subscription administrator roles, Azure roles, and Azure AD roles in the Azure RBAC documentation.

To view your role in your subscription, visit the subscriptions page in the Azure portal (you can use this link or look for Subscriptions with the portal search bar). Look for the name of the subscription you are using, and view your role for it in the My role column:

Screenshot of the Subscriptions page in the Azure portal, showing user as an owner.

If you find that the value is Contributor, or another role that doesn't have the required permissions described above, you can contact the user on your subscription that does have these permissions (such as a subscription Owner or Account admin) and proceed in one of the following ways:

  • Request that they complete the role assignment steps on your behalf.
  • Request that they elevate your role on the subscription so that you will have the permissions to proceed yourself. Whether this is appropriate depends on your organization and your role within it.

Assign the role

To give a user permissions to manage an Azure Digital Twins instance, you must assign them the Azure Digital Twins Data Owner role within the instance.

Use the following command to assign the role (must be run by a user with sufficient permissions in the Azure subscription). The command requires you to pass in the user principal name on the Azure AD account for the user that should be assigned the role. In most cases, this value will match the user's email on the Azure AD account.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<Azure-AD-user-principal-name-of-user-to-assign>" --role "Azure Digital Twins Data Owner"

The result of this command is outputted information about the role assignment that's been created.


If this command returns an error saying that the CLI cannot find user or service principal in graph database:

Assign the role using the user's Object ID instead. This may happen for users on personal Microsoft accounts (MSAs).

Use the Azure portal page of Azure Active Directory users to select the user account and open its details. Copy the user's ObjectID:

Screenshot of the user page in Azure portal highlighting the GUID in the 'Object ID' field.

Then, repeat the role assignment list command using the user's Object ID for the assignee parameter above.

Verify success

One way to check that you've successfully set up the role assignment is to view the role assignments for the Azure Digital Twins instance in the Azure portal. Go to your Azure Digital Twins instance in the Azure portal (you can look it up on the page of Azure Digital Twins instances or search its name in the portal search bar).

Then, view all of its assigned roles under Access control (IAM) > Role assignments. The user should show up in the list with a role of Azure Digital Twins Data Owner.

Screenshot of the role assignments for an Azure Digital Twins instance in the Azure portal.

You now have an Azure Digital Twins instance ready to go, and have assigned permissions to manage it.

Next steps

Test out individual REST API calls on your instance using the Azure Digital Twins CLI commands:

Or, see how to connect a client application to your instance with authentication code: