Try it free

Create an Azure connection via API

  • Latest Dynatrace
  • How-to guide

Prerequisites

1. Tools

The following CLI tools are required to run the commands on this page:

ToolMinimum versionNotes

curl

7.50

Must be built with HTTP/2 support (--http2 flag). Verify with curl --version—output should include HTTP2.

Azure CLI (az)

2.40

Required for service principal and role assignment commands. Verify with az version.

jq

1.5

Optional Used to extract values from JSON responses. Verify with jq --version.

2. Azure

Actions in this section must be performed by an Azure administrator with appropriate permissions.

Before running Azure CLI commands, ensure:

  • You have Azure CLI installed and authenticated (az login)

  • Your Azure account has one of the following:

    • Application Administrator role in Microsoft Entra ID

    • Cloud Application Administrator role in Microsoft Entra ID

    • microsoft.directory/servicePrincipals/create permission.

      And one of the following:

    • Owner role at the target scope (subscription or management group)

    • User Access Administrator role at the target scope

    • A custom role with Microsoft.Authorization/roleAssignments/write permission

For Management Group monitoring scope, you need role assignment permissions at the management group level, not just individual subscriptions.

Identify your Azure monitoring scope

Decide which monitoring scope you'll use and gather the required IDs:

Monitoring scopeRequired information
Management GroupManagement Group ID (found in Azure portal under Management groups)
SubscriptionSubscription ID (found in Azure portal under Subscriptions)

3. Dynatrace

  1. Create a programmatic access permission policy with the following permissions:

    ALLOW
      settings:objects:read,
      settings:objects:write,
      settings:schemas:read
      WHERE settings:schemaId = "builtin:hyperscaler-authentication.connections.azure";
    

    ALLOW
      extensions:definitions:read,
      extensions:definitions:write,
      extensions:configurations:read,
      extensions:configurations:write
      WHERE extensions:extension-name = "com.dynatrace.extension.da-azure";

  2. Create a service user and assign the policy created in step 1 to it.

  3. Create a platform token for the service user created in step 2 with the following scopes:

    extensions:configurations:read
    extensions:configurations:write
    extensions:definitions:read
    extensions:definitions:write
    settings:schemas:read
    settings:objects:read
    settings:objects:write

  4. If this is the first time an Azure connection is created in this Dynatrace environment, install the Azure extension. For more info on this API call, see Hub capabilities API - POST an extension 2.0 to environment.

    curl -X POST \
    '<YOUR_ENVIRONMENT_URL>/api/v2/hub/extensions2/com.dynatrace.extension.da-azure/actions/addToEnvironment' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -H 'Accept: application/json'

  5. Replace the following placeholders with your values:

    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com).
    • <YOUR_BEARER_TOKEN>: Platform token created in step 3.

Create a new Azure connection via REST API

The monitoring configuration requires an Azure connection to access your Azure environment.

Select the authentication method:

Authentication methodDescriptionNotes

Federated identity Recommended

Uses federated identity credentials.

More secure, passwordless authentication

Client secret

Uses a service principal with client secret.

Password-based authentication

Windows

The shell commands on this page use \ for line continuation (bash/zsh). On Windows, replace \ with a backtick (`) in PowerShell, or ^ in command prompt.

Federated identity credentials provide passwordless authentication and are more secure than client secrets.

This is the recommended approach for production environments.

1. Create an empty Azure connection

  1. Prepare the request payload.

    [
       {
          "value": {
                "federatedIdentityCredentials": {
                   "consumers": ["SVC:com.dynatrace.da"]
                },
                "name": "<CONNECTION_NAME>",
                "type": "federatedIdentityCredentials"
          },
          "schemaId": "builtin:hyperscaler-authentication.connections.azure"
       }
    ]

  2. Replace the <CONNECTION_NAME> placeholder with a descriptive name for the connection.

  3. Prepare the request to the REST API endpoint.

    curl -X 'POST' \
    '<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects?validateOnly=false&adminAccess=false' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<REQUEST_PAYLOAD>'

  4. Replace the following placeholders with your values:

    • <YOUR_BEARER_TOKEN>: Settings platform token

    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment

    • <REQUEST_PAYLOAD>: Request payload prepared in the previous step

  5. Send the request to the REST API endpoint. Successful request will respond with a connection ID:

    [
       {
          "code": 200,
          "objectId": "vu9U3hXa3q0AAAABADRidWlsdGlu..."
       }
    ]

  6. Save the objectId value. You'll need it for the next steps.

2. Configure federated credentials in Azure

Configure the federated identity credential in Microsoft Entra ID for your service principal using the connection ID from the last step above.

  1. Register a new application in your Microsoft Entra ID tenant.

    See How to register an app in Microsoft Entra ID to learn more.

    az ad sp create-for-rbac \
    --name "<CONNECTION_NAME>" \
    --create-password false \
    --query "{CLIENT_ID:appId, TENANT_ID:tenant}" \
    --output table

  2. Replace the <CONNECTION_NAME> placeholder with a descriptive name for the connection (used in Dynatrace).

  3. Create a federated credential for the Microsoft Entra ID app. Dynatrace uses this for OIDC token exchange.

    See az ad app federated-credential to learn more.

    az ad app federated-credential create \
    --id "<CLIENT_ID>" \
    --parameters '{"name": "<CONNECTION_NAME>-Federated-Credential", \
    "issuer": "https://token.dynatrace.com", \
    "subject": "dt:connection-id/<CONNECTION_ID_FROM_STEP_1>", \
    "audiences": ["<DYNATRACE_ENVIRONMENT_ID>.apps.dynatrace.com/svc-id/com.dynatrace.da"]}'

  4. Replace the following placeholders with your values:

    • <CLIENT_ID>: Application (client) ID from the previous step
    • <CONNECTION_NAME>: Descriptive name for the federated credential
    • <CONNECTION_ID_FROM_STEP_1>: The connection ID returned in step 1
    • <DYNATRACE_ENVIRONMENT_ID>: Your Dynatrace environment ID (for example, abc12345)
    • <OBJECT_ID>: Object ID of the service principal (retrieved in step 3)

  5. Get the object ID of the service principal.

    az ad sp show --id "<CLIENT_ID>" --query "{OBJECT_ID:id}" --output table

  6. Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

    • For the Management Group scope:

      The --scope requires the management group resource ID, not its display name. To find it:

      az account management-group list --query "[].{name:name, displayName:displayName}" --output table

      Use the value in the Name column as <MANAGEMENT_GROUP_ID>.

      az role assignment create \
      --assignee-object-id "<OBJECT_ID>" \
      --role "Monitoring Reader" \
      --scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
      --assignee-principal-type ServicePrincipal \
      --description "Dynatrace Monitoring"

    • For the Subscription scope:

      az role assignment create \
      --assignee-object-id "<OBJECT_ID>" \
      --role "Monitoring Reader" \
      --scope "/subscriptions/<SUBSCRIPTION_ID>" \
      --assignee-principal-type ServicePrincipal \
      --description "Dynatrace Monitoring"

  7. Verify the role assignment was successful:

    az role assignment list --assignee "<OBJECT_ID>" --output table

    You should see the Monitoring Reader role listed at your specified scope.

3. Update the Azure connection with service principal details

  1. Prepare the updated payload.

    {
       "value": {
          "federatedIdentityCredentials": {
             "directoryId": "<TENANT_ID>",
             "applicationId": "<CLIENT_ID>",
             "consumers": ["SVC:com.dynatrace.da"]
          },
          "name": "<CONNECTION_NAME>",
          "type": "federatedIdentityCredentials"
       }
    }

  2. Replace the following placeholders with your values:

    • <CONNECTION_NAME>: Descriptive name for the connection (same as in step 1)
    • <TENANT_ID>: Microsoft Entra ID tenant (directory) ID
    • <CLIENT_ID>: Application (client) ID of the service principal

  3. Prepare the PUT request to update the connection.

    curl -X 'PUT' \
    '<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects/<AZURE_CONNECTION_ID>?validateOnly=false' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<UPDATE_PAYLOAD>'

  4. Replace the following placeholders with your values and send the PUT request to update the connection.

    • <YOUR_BEARER_TOKEN>: Settings platform token
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment
    • <AZURE_CONNECTION_ID>: The objectId returned in step 1.
    • <UPDATE_PAYLOAD>: Request payload prepared above

    Successful request will respond with the updated connection ID:

    {
       "code": 200,
       "objectId": "vu9U3hXa3q0AAAABADRidWlsdGlu..."
    }

If the API call fails, validate that:

  • You have access to the Settings API
  • Your settings platform token is valid and assigned to the correct Dynatrace environment/account.

After successful completion, you can proceed to Create the Azure monitoring configuration.

Client secret authentication uses a password-based credential. Consider using federated identity credentials for improved security in production environments.

1. Register a new application in Azure

  1. Register a new application in your Microsoft Entra ID tenant. This creates a service principal with a client secret.

    See How to register an app in Microsoft Entra ID to learn more.

    az ad sp create-for-rbac \
    --name "<CONNECTION_NAME>" \
    --query "{CLIENT_ID:appId, TENANT_ID:tenant, CLIENT_SECRET:password}" \
    --output table

  2. Replace the <CONNECTION_NAME> placeholder with a descriptive name for the connection (used in Dynatrace).

2. Get the object ID

Get the object ID of the service principal.

az ad sp show --id "<CLIENT_ID>" --query "{OBJECT_ID:id}" --output table

3. Assign the role

Assign the Monitoring Reader Azure RBAC built-in role to the service principal at the appropriate monitoring scope.

  • For the Management Group scope:

    The --scope requires the management group resource ID, not its display name. To find it:

    az account management-group list --query "[].{name:name, displayName:displayName}" --output table

    Use the value in the Name column as <MANAGEMENT_GROUP_ID>.

    az role assignment create \
    --assignee-object-id "<OBJECT_ID>" \
    --role "Monitoring Reader" \
    --scope "/providers/Microsoft.Management/managementGroups/<MANAGEMENT_GROUP_ID>" \
    --assignee-principal-type ServicePrincipal \
    --description "Dynatrace Monitoring"

  • For the Subscription scope:

    az role assignment create \
    --assignee-object-id "<OBJECT_ID>" \
    --role "Monitoring Reader" \
    --scope "/subscriptions/<SUBSCRIPTION_ID>" \
    --assignee-principal-type ServicePrincipal \
    --description "Dynatrace Monitoring"

4. Verify

Verify the role assignment was successful:

az role assignment list --assignee "<OBJECT_ID>" --output table

You should see the Monitoring Reader role listed at your specified scope.

5. Prepare the JSON

  1. Prepare the request payload with your Azure service principal credentials.

    [
    	{
    		"value": {
    			"clientSecret": {
    				"directoryId": "<TENANT_ID>",
    				"applicationId": "<CLIENT_ID>",
    				"clientSecret": "<CLIENT_SECRET>",
    				"consumers": ["SVC:com.dynatrace.da"]
    			},
    			"name": "<CONNECTION_NAME>",
    			"type": "clientSecret"
    		},
    		"schemaId": "builtin:hyperscaler-authentication.connections.azure"
    	}
    ]

  2. Replace the following placeholders with your values:

    • <TENANT_ID>: Microsoft Entra ID tenant (directory) ID
    • <CLIENT_ID>: Application (client) ID of the service principal
    • <CLIENT_SECRET>: Client secret value from step 1
    • <CONNECTION_NAME>: Descriptive name for the connection

  3. Prepare the request to the REST API endpoint.

    curl -X 'POST' \
    '<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects?validateOnly=false&adminAccess=false' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<REQUEST_PAYLOAD>'

  4. Replace the following placeholders with your values and send the request to the REST API endpoint.

    • <YOUR_BEARER_TOKEN>: Settings platform token (from Prerequisites)
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <REQUEST_PAYLOAD>: Request payload prepared in the previous step

    Successful request will respond with the new Azure connection ID (in objectId field):

    [
    	{
    		"code": 200,
    		"objectId": "vu9U3hXa3q0AAAABADRidWlsdGlu...."
    	}
    ]

  5. Save the objectId value. You'll need it for creating the monitoring configuration.

Create a new Azure monitoring configuration via REST API

The monitoring configuration is the blueprint that contains all the settings that will be used on initial Azure onboarding (Azure services to poll metrics for, monitored regions, filtering rules, and more).

Settings can be modified post onboarding.

Get API schema version

The monitoring configuration API schema is versioned.

  1. Fetch the active version before constructing your request payload.

    curl -X 'GET' \
    "<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions?filter=name='com.dynatrace.extension.da-azure'&add-fields=activeVersion" \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

    Replace the following placeholders with your values:

    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <YOUR_BEARER_TOKEN>: Settings platform token (from Prerequisites)

    The response contains the active schema version:

    {
    "items": [
       {
          "extensionName": "com.dynatrace.extension.da-azure",
          "version": "1.0.5",
          "activeVersion": "1.0.0"
       }
    ],
    "totalCount": 1
    }

  2. Use the activeVersion value as <API_SCHEMA_VERSION> in the monitoring configuration payload.

Basic monitoring configuration

  1. Prepare the request payload.

    To get all valid values for locationFiltering and featureSets, query the extension schema:

    curl -X 'GET' \
    '<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/<API_SCHEMA_VERSION>/schema' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

    Extract valid location names:

    | jq '[.enums["dynatrace.datasource.azure:location"].items[].value]'

    Extract valid feature set names:

    | jq '[.enums["FeatureSetsType"].items[].value]'
    Required

    To allow telemetry signals-in-context and inventory on all relevant regions, the topology service must poll for topology signals on all regions where any signal is ingested.

    {
    	"scope": "integration-azure",
    	"value": {
    		"enabled": true,
    		"description": "<CONFIGURATION_NAME>",
    		"version": "<API_SCHEMA_VERSION>",
    		"featureSets": [
             "microsoft_compute.virtualmachines_essential",
             "microsoft_storage.storageaccounts_essential",
             "microsoft_web.sites_functionapp_essential"
    		],
    		"azure": {
    			"subscriptionFilteringMode": "INCLUDE",
    			"credentials": [
    				{
    					"description": "<CONFIGURATION_NAME>",
    					"enabled": true,
    					"connectionId": "<AZURE_CONNECTION_ID>",
    					"servicePrincipalId": "<CLIENT_ID>"
    				}
    			],
    			"locationFiltering": [
    				"<MONITORED_REGION_1>",
    				"<MONITORED_REGION_2>"
    			]
    		}
    	}
    }

    Replace the following placeholders with your values:

    • <CONFIGURATION_NAME>: Name of the monitoring configuration (letters, numbers, hyphens only; must start with a letter)
    • <AZURE_CONNECTION_ID>: The objectId returned in the Azure connection step
    • <CLIENT_ID>: Application (client) ID of the service principal
    • <MONITORED_REGION_1>, <MONITORED_REGION_2>: Azure regions to monitor (for example, eastus, westeurope, northeurope)
    • <API_SCHEMA_VERSION>: Active schema version from the Get API schema version step

  2. Send the POST request.

    curl -X 'POST' \
    '<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/monitoring-configurations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<REQUEST_PAYLOAD>'

    Successful request responds with the new monitoring configuration ID:

    {
      "objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
      "code": 200
    }

  3. Save the objectId value. You'll need it to modify or delete the configuration later.

Advanced configuration options

The monitoring configuration supports additional filtering and enrichment options to customize what resources are monitored and how data is enriched in Dynatrace.

Subscription filtering

Control which Azure subscriptions to monitor using subscriptionFiltering and subscriptionFilteringMode.

  • Include mode: Monitor only specified subscriptions:

    "subscriptionFiltering": [
    	"00000000-0000-0000-0000-000000000001",
    	"00000000-0000-0000-0000-000000000002"
    ],
    "subscriptionFilteringMode": "INCLUDE"

  • Exclude mode: Monitor all subscriptions except specified ones:

    "subscriptionFiltering": [
    	"00000000-0000-0000-0000-000000000001"
    ],
    "subscriptionFilteringMode": "EXCLUDE"

Tag filtering

Filter which Azure resources to monitor based on their tags using tagFiltering.

  • Include mode: Monitor only resources with matching tags:

    "tagFiltering": [
    	{
    		"key": "environment",
    		"value": "production",
    		"condition": "INCLUDE"
    	},
    	{
    		"key": "monitoring",
    		"value": "enabled",
    		"condition": "INCLUDE"
    	}
    ]

  • Exclude mode: Monitor all resources except those with matching tags:

    "tagFiltering": [
    	{
    		"key": "monitoring",
    		"value": "disabled",
    		"condition": "EXCLUDE"
    	}
    ]

Tag enrichment

Enrich Dynatrace signals with Azure resource tags by specifying tag keys in tagEnrichment. The specified Azure tag keys will be added as attributes to signals in Dynatrace.

"tagEnrichment": [
	"environment",
	"cost-center",
	"application",
	"team"
]

Label enrichment for cost allocation and security context

Map Azure tags or literal values to Dynatrace labels using dtLabelsEnrichment. This is particularly useful for cost allocation (dt.cost.costcenter, dt.cost.product) and security context (dt.security_context).

  • Using literal values

    "dtLabelsEnrichment": {
    	"dt.security_context": {
    		"literal": "production"
    	},
    	"dt.cost.costcenter": {
    		"literal": "CC-12345"
    	},
    	"dt.cost.product": {
    		"literal": "MyProduct"
    	}
    }

  • Using Azure tags

    "dtLabelsEnrichment": {
    	"dt.security_context": {
    		"tagKey": "environment"
    	},
    	"dt.cost.costcenter": {
    		"tagKey": "cost-center"
    	},
    	"dt.cost.product": {
    		"tagKey": "product-name"
    	}
    }

When using tagKey, the value of the specified Azure tag will be used as the label value in Dynatrace. Use literal for a fixed string value, or tagKey for a dynamic value from an Azure tag—not both.

Complete example with advanced options
{
	"scope": "integration-azure",
	"value": {
		"enabled": true,
		"description": "production-monitoring",
		"version": "<API_SCHEMA_VERSION>",
		"featureSets": [
         "microsoft_compute.virtualmachines_essential",
         "microsoft_storage.storageaccounts_essential",
         "microsoft_web.sites_functionapp_essential"
		],
		"azure": {
			"credentials": [
				{
					"description": "production-monitoring",
					"enabled": true,
					"connectionId": "vu9U3hXa3q0AAAABADRidWlsdGlu...",
					"servicePrincipalId": "00000000-0000-0000-0000-000000000000"
				}
			],
			"locationFiltering": [
				"westeurope",
				"northeurope",
				"eastus"
			],
			"subscriptionFiltering": [
				"00000000-0000-0000-0000-000000000001",
				"00000000-0000-0000-0000-000000000002"
			],
			"subscriptionFilteringMode": "INCLUDE",
			"tagFiltering": [
				{
					"key": "environment",
					"value": "production",
					"condition": "INCLUDE"
				},
				{
					"key": "monitoring",
					"value": "disabled",
					"condition": "EXCLUDE"
				}
			],
			"tagEnrichment": [
				"environment",
				"cost-center",
				"application",
				"team"
			],
			"dtLabelsEnrichment": {
				"dt.security_context": {
					"tagKey": "environment"
				},
				"dt.cost.costcenter": {
					"tagKey": "cost-center"
				},
				"dt.cost.product": {
					"literal": "Platform"
				}
			}
		}
	}
}

  1. Prepare the REST API request.

    curl -X 'POST' \
    '<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/monitoring-configurations' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<MONITORING_CONFIG_PAYLOAD>'

    Replace the following placeholders with your values and send the REST API request.

    • <YOUR_BEARER_TOKEN>: Settings platform token (from Prerequisites)
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <MONITORING_CONFIG_PAYLOAD>: Request payload prepared in the previous step

  2. Successful request will respond with new monitoring configuration ID (in objectId field):

    {
       "objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
       "code": 200
    }

    If the API call fails, validate that

    • You have access to the Settings API
    • Your settings platform token is valid and assigned to the correct Dynatrace environment/account

  3. After successful completion, head over to Settings Settings > Cloud and virtualization > Azure.

    In the next few minutes the newly created connection should be visible and Healthy.

Modify an existing monitoring configuration

To modify an existing monitoring configuration

  1. Retrieve existing configuration using GET request.

    curl -X 'GET' \
    '<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/monitoring-configurations/<MONITORING_CONFIG_ID>' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

    Replace the following placeholders with your values:

    • <YOUR_BEARER_TOKEN>: Settings platform token
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <MONITORING_CONFIG_ID>: ID of the monitoring configuration you want to modify

  2. Modify the retrieved configuration JSON as needed (for example, add/remove monitored regions, enable/disable feature sets, update filtering rules).

  3. Update the configuration using PUT request.

    Replace the following placeholders with your values:

    • <YOUR_BEARER_TOKEN>: Settings platform token
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <MONITORING_CONFIG_ID>: ID of the monitoring configuration you want to modify
    • <MODIFIED_CONFIG_PAYLOAD>: Modified configuration JSON from step 2
    curl -X 'PUT' \
    '<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/monitoring-configurations/<MONITORING_CONFIG_ID>' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<MODIFIED_CONFIG_PAYLOAD>'

    Successful request will respond with updated monitoring configuration ID:

    {
    "objectId": "e4bf05f3-d829-3689-8dd4-a9d2aeab0607",
    "code": 200
    }

Delete an existing monitoring configuration

To delete an existing monitoring configuration

  1. Replace the following placeholders with your values:

    • <YOUR_BEARER_TOKEN>: Settings platform token
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <MONITORING_CONFIG_ID>: ID of the monitoring configuration you want to delete
    curl -X 'DELETE' \
    '<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/monitoring-configurations/<MONITORING_CONFIG_ID>' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

  2. Successful request will respond with 204 No Content status, indicating that the configuration has been deleted successfully.

A deleted monitoring configuration does not delete any supporting Azure resources deployed in your environment (for example, logs infrastructure).

You must delete these manually to avoid lingering resources which will incur Azure and Dynatrace costs.

Roll over a client secret

This procedure applies to connections that use client secret authentication. If you want to eliminate ongoing secret rotation, consider migrating to federated identity credentials instead.

Update the connection in Dynatrace before the existing secret expires to avoid a monitoring gap.

If you didn't save <AZURE_CONNECTION_ID> when you created the connection, retrieve it with:

curl -X 'GET' \
'<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects?schemaIds=builtin:hyperscaler-authentication.connections.azure' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

The objectId field in the response is your <AZURE_CONNECTION_ID>.

  1. Replace the following placeholders with your values:

    • <APPLICATION_ID>: Application (client) ID of the Azure service principal
    • <CONNECTION_NAME>: Name of the existing Dynatrace Azure connection
    • <TENANT_ID>: Microsoft Entra ID tenant (directory) ID
    • <CLIENT_ID>: Application (client) ID of the service principal
    • <NEW_CLIENT_SECRET>: New client secret generated in step 2—save it immediately, it cannot be retrieved later
    • <OLD_KEY_ID>: The keyId of the old credential captured in step 1
    • <YOUR_BEARER_TOKEN>: Settings platform token (from Prerequisites)
    • <YOUR_ENVIRONMENT_URL>: URL of your Dynatrace environment (for example, https://abc12345.apps.dynatrace.com)
    • <AZURE_CONNECTION_ID>: The objectId of the Azure connection, returned when it was created

  2. List the current credentials for your service principal to capture the keyId of the existing secret.

    az ad app credential list --id "<APPLICATION_ID>" --output table

    Note the keyId value. You'll need it in step 6 to remove the old secret.

  3. Generate a new client secret. The --append flag adds the new credential without invalidating the existing one, so Dynatrace monitoring continues uninterrupted during the rollover.

    az ad app credential reset \
    --id "<APPLICATION_ID>" \
    --append \
    --display-name "Dynatrace rollover $(date +%Y-%m-%d)" \
    --query password \
    --output tsv

    The command outputs the new secret. Save this value as <NEW_CLIENT_SECRET>—it cannot be retrieved again after this point.

  4. Prepare the update payload with the new secret value.

    {
      "value": {
        "clientSecret": {
          "directoryId": "<TENANT_ID>",
          "applicationId": "<CLIENT_ID>",
          "clientSecret": "<NEW_CLIENT_SECRET>",
          "consumers": ["SVC:com.dynatrace.da"]
        },
        "name": "<CONNECTION_NAME>",
        "type": "clientSecret"
      }
    }

  5. Send the PUT request to update the connection.

    curl -X 'PUT' \
    '<YOUR_ENVIRONMENT_URL>/platform/classic/environment-api/v2/settings/objects/<AZURE_CONNECTION_ID>?validateOnly=false' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
    -d '<REQUEST_PAYLOAD>'

    Successful request will respond with the updated connection ID (objectId):

    {
      "code": 200,
      "objectId": "vu9U3hXa3q0AAAABADRidWlsdGlu..."
    }

  6. Once the connection is Healthy in Dynatrace, remove the old secret from Azure.

    az ad app credential delete \
    --id "<APPLICATION_ID>" \
    --key-id "<OLD_KEY_ID>"

What's next?

  • To enable Azure log and event ingestion, deploy the ARM template for your connection. See Azure logs and events.
  • Go to Clouds Clouds. Azure resources with telemetry should start to appear shortly.

Supported Azure services

For a full list of supported Azure services, including topology relationships and available metric collection sets, see Supported Azure services.

Troubleshooting

Error: "Authorization_RequestDenied" when creating the service principal

This error occurs when your Azure identity lacks permission to create applications in Microsoft Entra ID.

Solution: Ask your Azure administrator to grant you the Application Administrator role or create the service principal on your behalf.

Error: "AuthorizationFailed" when assigning the Monitoring Reader role

This error occurs when your Azure identity lacks permission to assign roles at the specified scope.

Solution:

  • Ensure you have the Owner or User Access Administrator role at the target subscription or management group.
  • For the Management Group scope, confirm you have permissions at the management group level, not just individual subscriptions.
  • If using Management Group scope, verify you are using the resource ID in --scope, not the display name. Run az account management-group list and use the Name column value — display names differ from IDs and produce the same error.
Error: "AADSTS70025" when updating the Azure connection

This error indicates that Microsoft Entra ID has not yet propagated the federated credential.

Solution: Wait a few seconds for propagation to complete, then retry the API call.

Monitoring configuration curl request hangs with no response

Some environments return no HTTP response to curl requests against the /platform/extensions/v2/ endpoints, causing the command to hang until a timeout.

Solution: Add --http2 to force HTTP/2:

curl --http2 -X 'POST' \
'<YOUR_ENVIRONMENT_URL>/platform/extensions/v2/extensions/com.dynatrace.extension.da-azure/monitoring-configurations' \
...

Verify your curl build includes HTTP/2 support by running curl --version — the output should include HTTP2 in the features list.

Related tags
Infrastructure Observability