| title | Create endpoints | ||
|---|---|---|---|
| titleSuffix | Azure Digital Twins | ||
| description | Learn how to set up endpoints for Azure Digital Twins data | ||
| author | baanders | ||
| ms.author | baanders | ||
| ms.date | 06/19/2025 | ||
| ms.topic | how-to | ||
| ms.service | azure-digital-twins | ||
| ms.custom |
|
This article explains how to create an endpoint for Azure Digital Twin events using the Azure portal or the Azure CLI. You can also manage endpoints with the DigitalTwinsEndpoint control plane APIs.
Routing event notifications from Azure Digital Twins to downstream services or connected compute resources is a two-step process: create endpoints, then create event routes that send data to those endpoints. This article covers the first step, setting up endpoints that can receive the events. Later, you can create event routes that specify which events generated by Azure Digital Twins are delivered to which endpoints.
-
An Azure account, which you can set up for free.
-
An Azure Digital Twins instance in your Azure subscription. If you don't have an instance, create one by following the steps in Set up an instance and authentication. Have the following values from setup available to use later in this article:
- Instance name
- Resource group
You can find these details in the Azure portal after setting up your instance.
:::image type="content" source="media/includes/instance-details.png" alt-text="Screenshot of the Overview page for an Azure Digital Twins instance in the Azure portal. The name and resource group are highlighted." lightbox="media/includes/instance-details.png":::
If you intend to use the Azure CLI while following this guide, follow the instructions in the next section.
[!INCLUDE azure-cli-prepare-your-environment-h3.md]
These services are the supported types of endpoints that you can create for your instance:
- Event Grid topic
- For Event Grid endpoints, only Event Grid topics are supported. Event Grid domains aren't supported as endpoints.
- Event Hubs hub
- Service Bus topic
Before you link an endpoint to Azure Digital Twins, you need to create the Event Grid topic, event hub, or Service Bus topic that you're using for the endpoint.
Use the following chart to see what resources you should set up before creating your endpoint.
| Endpoint type | Required resources (linked to creation instructions) |
|---|---|
| Event Grid endpoint | Event Grid topic (Event schema must be Event Grid Schema or Cloud Event Schema v1.0) |
| Event Hubs endpoint | Event Hubs namespace event hub (Optional) Authorization rule for key-based authentication |
| Service Bus endpoint | Service Bus namespace Service Bus topic (Optional) Authorization rule for key-based authentication |
After creating the endpoint resources, you can create the Azure Digital Twins endpoint. Use the following tabs to select your preferred experience.
To create a new endpoint, go to your instance's page in the Azure portal. You can find the instance by entering its name into the portal search bar.
-
From the instance menu, select Connect outputs > Endpoints. Then from the Endpoints page, select + Create an endpoint. This action opens the Create an endpoint page.
:::image type="content" source="media/how-to-create-endpoints/create-endpoint-event-grid.png" alt-text="Screenshot of creating an endpoint of type Event Grid in the Azure portal." lightbox="media/how-to-create-endpoints/create-endpoint-event-grid.png":::
-
Enter a Name for your endpoint and choose the Endpoint type.
-
Complete the other details that are required for your endpoint type, including your subscription and the endpoint resources described earlier.
- For Event Hubs and Service Bus endpoints only, select an Authentication type. You can use key-based authentication with a precreated authorization rule, or a system-assigned or user-assigned managed identity. System-assigned identity is only available if you've enabled a system-assigned identity for the instance. For more information about using the identity authentication options, see Endpoint options: Identity-based authentication later in this article..
:::image type="content" source="media/how-to-create-endpoints/create-endpoint-event-hub-authentication.png" alt-text="Screenshot of creating an endpoint of type Event Hubs in the Azure portal." lightbox="media/how-to-create-endpoints/create-endpoint-event-hub-authentication.png":::
-
Finish creating your endpoint by selecting Save.
After creating your endpoint, you can verify that it was successfully created by checking the notification icon in the top Azure portal bar:
:::image type="content" source="media/how-to-create-endpoints/create-endpoint-notifications.png" alt-text="Screenshot of the notification to verify the creation of an endpoint in the Azure portal.":::
If the endpoint creation fails, observe the error message and retry after a few minutes.
You can also view the endpoint that you created on the Endpoints page for your Azure Digital Twins instance.
Now the Event Grid topic, event hub, or Service Bus topic is available as an endpoint in Azure Digital Twins, under the name you chose for the endpoint. Typically, you use that name as the target of an event route, which you can create in Create routes and filters.
The following examples show how to create endpoints using the az dt endpoint create command for the Azure Digital Twins CLI. Replace the placeholders in the commands with the details of your own resources.
To create an Event Grid endpoint:
az dt endpoint create eventgrid --endpoint-name <Event-Grid-endpoint-name> --eventgrid-resource-group <Event-Grid-resource-group-name> --eventgrid-topic <your-Event-Grid-topic-name> --dt-name <your-Azure-Digital-Twins-instance-name>
To create an Event Hubs endpoint (key-based authentication):
az dt endpoint create eventhub --endpoint-name <Event-Hub-endpoint-name> --eventhub-resource-group <Event-Hub-resource-group> --eventhub-namespace <Event-Hub-namespace> --eventhub <Event-Hub-name> --eventhub-policy <Event-Hub-policy> --dt-name <your-Azure-Digital-Twins-instance-name>
To create a Service Bus topic endpoint (key-based authentication):
az dt endpoint create servicebus --endpoint-name <Service-Bus-endpoint-name> --servicebus-resource-group <Service-Bus-resource-group-name> --servicebus-namespace <Service-Bus-namespace> --servicebus-topic <Service-Bus-topic-name> --servicebus-policy <Service-Bus-topic-policy> --dt-name <your-Azure-Digital-Twins-instance-name>
After you run these commands, the Event Grid topic, event hub, or Service Bus topic is available as an endpoint in Azure Digital Twins. The endpoint has the name you supplied with the --endpoint-name argument. Typically, you use that name as the target of an event route, which you can create in Create routes and filters.
This section describes how to use a managed identity for an Azure Digital Twins instance when forwarding events to supported routing destinations. Setting up a managed identity isn't required for routing, but it can help the instance to easily access other Microsoft Entra protected resources, such as Event Hubs, Service Bus destinations, and Azure Storage Container. Managed identities can be system-assigned or user-assigned.
The rest of this section walks through three steps for setting up an endpoint with a managed identity.
Use the following tabs for instructions that match your preferred experience.
First, make sure that you enable a managed identity for your Azure Digital Twins instance.
Also, make sure you have Azure Digital Twins Data Owner role on the instance. You can find instructions in Set up user access permissions.
First, make sure that you enabled a managed identity for your Azure Digital Twins instance.
Also, make sure you have Azure Digital Twins Data Owner role on the instance. For instructions, see Set up user access permissions.
After you create a managed identity for your Azure Digital Twins instance, assign it appropriate roles to authenticate with different types of endpoints for routing events to supported destinations. This section describes the role options and how to assign them to the managed identity.
Important
Make sure to complete this step. Without it, the identity can't access your endpoints and events aren't delivered.
Here are the minimum roles that your Azure Digital Twins identity needs to access an endpoint, depending on the type of destination. Roles with higher permissions (like Data Owner roles) also work.
| Destination | Azure role |
|---|---|
| Azure Event Hubs | Azure Event Hubs Data Sender |
| Azure Service Bus | Azure Service Bus Data Sender |
| Azure storage container | Storage Blob Data Contributor |
Use the following tabs to assign the role using your preferred experience.
To assign a role to the identity, open the Azure portal in a browser.
-
Navigate to your endpoint resource (your event hub, Service Bus topic, or storage container) by searching for its name in the portal search bar.
-
Select Access control (IAM).
-
Select Add > Add role assignment to open the Add role assignment page.
-
Assign the desired role to the managed identity of your Azure Digital Twins instance. For detailed steps, see Assign Azure roles using the Azure portal.
Setting Value Role Select the desired role from the options. Assign access to Managed identity
| Members | Select the user-assigned or system-assigned managed identity of your Azure Digital Twins instance that's being assigned the role. A user-assigned identity has the name you chose when you created the identity, and a system-assigned identity has a name that matches the name of your Azure Digital Twins instance. |
:::image type="content" source="/reusable-content/ce-skilling/azure/media/role-based-access-control/add-role-assignment-page.png" alt-text="Screenshot of the 'Add role assignment' page for an Azure Digital Twins instance." lightbox="/reusable-content/ce-skilling/azure/media/role-based-access-control/add-role-assignment-page.png":::
You can add the --scopes parameter onto the az dt create command to assign the identity to one or more scopes with a specified role. Use this command when first creating the instance, or later by passing in the name of an existing instance.
Here's an example that creates an instance with a system-assigned managed identity, and assigns that identity a custom role called MyCustomRole in an event hub.
az dt create --dt-name <new-instance-name> --resource-group <resource-group> --mi-system-assigned --scopes "/subscriptions/<subscription ID>/resourceGroups/<resource-group>/providers/Microsoft.EventHub/namespaces/<Event-Hubs-namespace>/eventhubs/<event-hub-name>" --role MyCustomRole
For more examples of role assignments with this command, see the az dt create reference documentation.
You can also use the az role assignment command group to create and manage roles. Use this command to support other scenarios where you don't want to group role assignment with the create command.
After setting up a managed identity for your Azure Digital Twins instance and assigning it the appropriate roles, create the endpoints that use the identity for authentication. This option is only available for Event Hubs and Service Bus-type endpoints (it's not supported for Event Grid).
Note
You can't edit an endpoint that you created with key-based identity to change to identity-based authentication. You must choose the authentication type when you first create the endpoint.
Use the following sections to create the endpoint using your preferred experience.
Start following the general instructions to create an Azure Digital Twins endpoint.
When you get to the step of completing the details required for your endpoint type, select either System-assigned or User-assigned (preview) for the Authentication type.
:::image type="content" source="media/how-to-create-endpoints/create-endpoint-event-hub-authentication.png" alt-text="Screenshot of creating an endpoint of type Event Hubs." lightbox="media/how-to-create-endpoints/create-endpoint-event-hub-authentication.png":::
Finish setting up your endpoint and select Save.
Add managed identities to an endpoint by adding parameters to the az dt endpoint create command. For more information about this command, see its reference documentation or the general instructions to create an Azure Digital Twins endpoint.
Use the following CLI command for your chosen type of managed identity.
To create an endpoint that uses system-assigned authentication, specify the IdentityBased authentication type with the --auth-type parameter. The following example illustrates this functionality for an Event Hubs endpoint.
az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --auth-type IdentityBased
To create an endpoint that uses user-assigned identity authentication, specify the user assigned identity resource ID with the --user parameter. The following example illustrates this functionality for an Event Hubs endpoint.
az dt endpoint create eventhub --endpoint-name <endpoint-name> --eventhub-resource-group <eventhub-resource-group> --eventhub-namespace <eventhub-namespace> --eventhub <eventhub-name> --dt-name <instance-name> --user <user-assigned-identity-resource-ID>
An identity is managed separately from the endpoints that use it, so it's important to consider how any change to the identity or its roles can affect the endpoints in your Azure Digital Twins instance. If you disable the identity or remove a necessary role for an endpoint, the endpoint becomes inaccessible, and the flow of events is disrupted.
To continue using an endpoint that was set up with a managed identity that you disabled, delete the endpoint and re-create it with a different authentication type. It might take up to an hour for events to resume delivery to the endpoint after this change.
When an endpoint can't deliver an event within a certain time period or number of tries, it can send the undelivered event to a storage account. This process is known as dead-lettering.
You can set up the necessary storage resources using the Azure portal or the Azure Digital Twins CLI. However, to create an endpoint with dead-lettering enabled, you need to use the Azure Digital Twins CLI or control plane APIs.
To learn more about dead-lettering, see Endpoints and event routes. For instructions on how to set up an endpoint with dead-lettering, continue through the rest of this section.
Before setting the dead-letter location, you must have a storage account with a container in your Azure account.
When creating the endpoint, you provide the URI of this container. The dead-letter location is provided to the endpoint as a container URI with a SAS token. That token needs write permission for the destination container within the storage account. The fully formed dead letter SAS URI is in the format of: https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>.
To set up these storage resources in your Azure account, follow the steps in the following section. After setting up the storage resources, you can set up the endpoint connection.
- To create a storage account in your Azure subscription, follow the steps in Create a storage account. Make a note of the storage account name so you can use it later.
- To create a container within the new storage account, follow the steps in Create a container. Make a note of the container name so you can use it later.
Next, create a SAS token for your storage account that the endpoint can use to access it.
-
Navigate to your storage account in the Azure portal (you can find it by name with the portal search bar).
-
In the storage account page, choose the Security + networking > Shared access signature link in the left navigation bar to start setting up the SAS token.
:::image type="content" source="media/how-to-create-endpoints/generate-token.png" alt-text="Screenshot of the storage account page in the Azure portal." lightbox="media/how-to-create-endpoints/generate-token.png":::
-
On the Shared access signature page, under Allowed services and Allowed resource types, select the settings you want. You need to select at least one box in each category. Under Allowed permissions, choose Write. You can also select other permissions.
-
Set the values you want for the remaining settings.
-
When you're finished, select Generate SAS and connection string to generate the SAS token.
-
Completing this process generates several SAS and connection string values at the bottom of the same page, underneath the setting selections. Scroll down to view the values, and use the Copy to clipboard icon to copy the SAS token value. Save it to use later.
-
Retrieve your storage account keys using the following command and copy the value for either one of your keys:
az storage account keys list --account-name <storage-account-name> -
Select an expiration date and generate the SAS token for your storage account using the following command:
az storage account generate-sas --account-name <storage-account-name> --account-key <storage-account-key> --expiry <expiration-date> --services bfqt --resource-types o --permissions wThe output of this command is the SAS token. Copy the SAS token value to use later.
[!NOTE] The example set of parameters in the previous command include "blob", "file", "queue", and "table" services (
--services bfqt), an "object" resource type (--resource-types o), and "write" permissions (--permissions w).For more information about the
az storage account generate-sascommand and its parameters, see the Azure CLI reference.
To create an endpoint with dead-lettering enabled, use the CLI commands or control plane APIs to create your endpoint. You can't create this type of endpoint in the Azure portal.
For instructions on how to create this type of endpoint with the Azure CLI, switch to the CLI tab for this section.
To create an endpoint that has dead-lettering enabled, add the --deadletter-sas-uri parameter to the az dt endpoint create command that creates an endpoint.
The value for the parameter is the dead letter SAS URI made up of the storage account name, container name, and SAS token that you gathered in the previous section. This parameter creates the endpoint with key-based authentication. Here's what the parameter looks like:
--deadletter-sas-uri https://<storage-account-name>.blob.core.windows.net/<container-name>?<SAS-token>
Tip
To create a dead-letter endpoint with identity-based authentication, add both the dead-letter parameter from this section and the appropriate managed identity parameter to the same command.
You can also create dead letter endpoints using the Azure Digital Twins control plane APIs instead of the CLI. To do so, view the DigitalTwinsEndpoint documentation to see how to structure the request and add the dead letter parameters.
Once you set up the endpoint with dead-lettering, the dead-lettered messages are stored in your storage account in the following format:
<container>/<endpoint-name>/<year>/<month>/<day>/<hour>/<event-ID>.json
The dead-lettered messages match the schema of the original event that your original endpoint was intended to deliver.
Here's an example of a dead-letter message for a twin create notification:
{
"specversion": "1.0",
"id": "xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "Microsoft.DigitalTwins.Twin.Create",
"source": "<your-instance>.api.<your-region>.da.azuredigitaltwins-test.net",
"data": {
"$dtId": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"$etag": "W/\"xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx\"",
"TwinData": "some sample",
"$metadata": {
"$model": "dtmi:test:deadlettermodel;1",
"room": {
"lastUpdateTime": "2020-10-14T01:11:49.3576659Z"
}
}
},
"subject": "<your-instance>xxxxxxxx-xxxxx-xxxx-xxxx-xxxxxxxxxxxx",
"time": "2020-10-14T01:11:49.3667224Z",
"datacontenttype": "application/json",
"traceparent": "00-889a9094ba22b9419dd9d8b3bfe1a301-f6564945cb20e94a-01"
}After you create an endpoint, define an event route to send data to the endpoint. Event routes allow you to set up event flow throughout the system and to downstream services. A single route can allow multiple notifications and event types. Create an event route to your endpoint with the instructions in Create routes and filters.