edits

Author: v-albemi

articles/api-management/api-management-howto-use-managed-service-identity.md

@@ -1,6 +1,6 @@
 ---
-title: Use managed identities in Azure API Management | Microsoft Docs
-description: Learn how to create system-assigned and user-assigned identities in API Management by using the Azure portal, PowerShell, and a Resource Manager template. Learn about supported scenarios with managed identities.
+title: Use Managed Identities in Azure API Management | Microsoft Docs
+description: Learn how to create system-assigned and user-assigned identities in API Management by using the Azure portal, PowerShell, and Resource Manager templates. Learn about supported scenarios with managed identities.
 services: api-management
 author: dlepow
 
@@ -9,51 +9,53 @@ ms.topic: how-to
 ms.date: 05/19/2025
 ms.author: danlep
 ms.custom: devx-track-azurepowershell
+
+#customer intent: As an API developer, I want to create managed identities so that API Management can access other resources. 
 ---
 
 # Use managed identities in Azure API Management
 
 [!INCLUDE [api-management-availability-all-tiers](../../includes/api-management-availability-all-tiers.md)]
 
-This article shows you how to create a managed identity for an Azure API Management instance and how to use it to access other resources. A managed identity generated by Microsoft Entra ID allows your API Management instance to easily and securely access other Microsoft Entra protected resources, such as Azure Key Vault. Azure manages this identity, so you don't have to provision or rotate any secrets. For more information about managed identities, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md).
+This article shows how to create a managed identity for an Azure API Management instance and how to use it to access other resources. A managed identity generated by Microsoft Entra ID enables API Management to easily and securely access other resources that are protected by Microsoft Entra, like Azure Key Vault. Azure manages these identities, so you don't have to provision or rotate any secrets. For more information about managed identities, see [What are managed identities for Azure resources?](../active-directory/managed-identities-azure-resources/overview.md).
 
 You can grant two types of identities to an API Management instance:
 
 - A *system-assigned identity* is tied to your service and is deleted if your service is deleted. The service can have only one system-assigned identity.
 - A *user-assigned identity* is a standalone Azure resource that can be assigned to your service. The service can have multiple user-assigned identities.
 
 > [!NOTE]
-> Managed identities are specific to the Microsoft Entra tenant where your Azure subscription is hosted. They don't get updated if a subscription is moved to a different directory. If a subscription is moved, you'll need to recreate and configure the identities.  
+> Managed identities are specific to the Microsoft Entra tenant in which your Azure subscription is hosted. They don't get updated if a subscription is moved to a different directory. If a subscription is moved, you need to re-create and reconfigure the identities.  
 
 [!INCLUDE [api-management-workspace-availability](../../includes/api-management-workspace-availability.md)]
 
 ## Create a system-assigned managed identity
 
 ### Azure portal
 
-To set up a managed identity in the Azure portal, you'll first create an API Management instance and then enable the feature.
+To set up a managed identity in the Azure portal, you create an API Management instance and then enable the feature.
 
-1. Create an API Management instance in the portal as you normally would. Browse to it in the portal.
+1. Create an API Management instance in the portal as you normally would. Go to it in the portal.
 2. In the left menu, under **Security**, select **Managed identities**.
 3. On the **System assigned** tab, switch **Status** to **On**. Select **Save**.
 
-    :::image type="content" source="./media/api-management-howto-use-managed-service-identity/enable-system-identity.png" alt-text="Selections for enabling a system-assigned managed identity" border="true":::
+    :::image type="content" source="./media/api-management-howto-use-managed-service-identity/enable-system-identity.png" alt-text="Screenshot that shows how to enable a system-assigned managed identity." border="true":::
 
 ### Azure PowerShell
 
 [!INCLUDE [updated-for-az](~/reusable-content/ce-skilling/azure/includes/updated-for-az.md)]
 
-The following steps walk you through creating an API Management instance and assigning it an identity by using Azure PowerShell.
+The following steps lead you through creating an API Management instance and assigning it an identity by using Azure PowerShell.
 
-1. If needed, install Azure PowerShell by using the instructions in the [Azure PowerShell guide](/powershell/azure/install-azure-powershell). Then run `Connect-AzAccount` to create a connection with Azure.
+1. If you need to, install Azure PowerShell by following the instructions in the [Azure PowerShell guide](/powershell/azure/install-azure-powershell). Then run `Connect-AzAccount` to create a connection with Azure.
 
-2. Use the following code to create the instance with a system-assigned managed identity. For more examples of how to use Azure PowerShell with an API Management instance, see [API Management PowerShell samples](powershell-samples.md).
+2. Use the following code to create the instance with a system-assigned managed identity. For more examples of how to use Azure PowerShell with API Management, see [API Management PowerShell samples](powershell-samples.md).
 
     ```azurepowershell-interactive
     # Create a resource group.
     New-AzResourceGroup -Name $resourceGroupName -Location $location
 
-    # Create an API Management Consumption Sku service.
+    # Create an API Management Consumption SKU service.
     New-AzApiManagement -ResourceGroupName $resourceGroupName -Name consumptionskuservice -Location $location -Sku Consumption -Organization contoso -AdminEmail [email protected] -SystemAssignedIdentity
     ```
 
@@ -77,9 +79,9 @@ You can create an API Management instance with a system-assigned identity by inc
 }
 ```
 
-This property tells Azure to create and manage the identity for your API Management instance.
+This property instructs Azure to create and manage the identity for your API Management instance.
 
-For example, a complete Azure Resource Manager template might look like the following:
+For example, a complete Azure Resource Manager template might look like this one:
 
 ```json
 {
@@ -119,11 +121,11 @@ When the instance is created, it has the following additional properties:
 The `tenantId` property identifies which Microsoft Entra tenant the identity belongs to. The `principalId` property is a unique identifier for the instance's new identity. Within Microsoft Entra ID, the service principal has the same name that you gave to your API Management instance.
 
 > [!NOTE]
-> An API Management instance can have both system-assigned and user-assigned identities at the same time. In this case, the `type` property would be `SystemAssigned,UserAssigned`.
+> An API Management instance can have both system-assigned and user-assigned identities at the same time. In that scenario, the `type` property is `SystemAssigned,UserAssigned`.
 
-## Configure Key Vault access using a managed identity
+## Configure Key Vault access by using a managed identity
 
-The following configurations are needed for API Management to access certificates from an Azure key vault.
+The following configurations are required if you want to use API Management to access certificates from an Azure key vault.
 
 [!INCLUDE [api-management-key-vault-certificate-access](../../includes/api-management-key-vault-certificate-access.md)]
 

includes/api-management-key-vault-access.md

@@ -7,15 +7,16 @@ ms.author: danlep
 ---
 
 ### Configure access to key vault
-1. In the portal, navigate to your key vault.
-1. In the left menu, select **Access configuration**, and note the **Permission model** that is configured.
+
+1. In the portal, go to your key vault.
+1. In the left menu, select **Access configuration**. Note the **Permission model** that's configured.
 1. Depending on the permission model, configure either a [key vault access policy](/azure/key-vault/general/assign-access-policy) or [Azure RBAC access](/azure/key-vault/general/rbac-guide) for an API Management managed identity.
 
-**To add a key vault access policy:<br/>**
+**To add a key vault access policy:**
 
 1. In the left menu, select **Access policies**.
 1. On the **Access policies** page, select **+ Create**.
-1. On the **Permissions** tab, under **Secret permissions**, select **Get** and **List**, then select **Next**.
+1. On the **Permissions** tab, under **Secret permissions**, select **Get** and **List**, and then select **Next**.
 1. On the **Principal** tab,  **Select principal**, search for  the resource name of your managed identity, and then select **Next**.
      If you're using a system-assigned identity, the principal is the name of your API Management instance.
 1. Select **Next** again. On the **Review + create** tab, select **Create**.

includes/api-management-key-vault-certificate-access.md

@@ -7,11 +7,11 @@ ms.author: danlep
 ---   
 [!INCLUDE [api-management-key-vault-access](api-management-key-vault-access.md)]
 
-**To configure Azure RBAC access:<br/>**
+**To configure Azure RBAC access:**
 
 1. In the left menu, select **Access control (IAM)**.
 1. On the **Access control (IAM)** page, select **Add role assignment**.
 1. On the **Role** tab, select **Key Vault Certificate User**.
 1. On the **Members** tab, select **Managed identity** > **+ Select members**.
-1. On the **Select managed identity** page, select the system-assigned managed identity or a user-assigned managed identity associated with your API Management instance, and then select **Select**.
+1. On the **Select managed identity** page, select the system-assigned managed identity or a user-assigned managed identity that's associated with your API Management instance, and then click **Select**.
 1. Select **Review + assign**.