Azure API Management | Purge Soft-Deleted Instance

Posted by Andrew Wilson on Wednesday, September 7, 2022

Problem Space:

Around June 2020 a change was made to Azure API Management whereby any deletion of the instance via the Azure portal, Azure PowerShell, Azure CLI, and REST API version 2020-06-01-preview or later will result in the instance being soft-deleted.

This is to allow for recoverability of a recently deleted API Management instance, and therefore protecting against accidental deletion of the instance.

The problem with this is that not all the Azure Resource Management tooling currently supports the management of soft deleted API Management Instances. Currently the only management tooling that supports this feature are the REST API and Azure CLI. You cannot at this point in time list, show, or purge a soft deleted instance in the Management Portal or Azure PowerShell.


Azure CLI

As of the 5th of July 2022, you can use the Azure CLI to manage soft-deleted APIM instances. Specifically CLI version 2.38.0 and above.

Documentation on the relative management actions that can be applied are shown here.

To purge a deleted instance, you can use the following commands:

az login

az account set --subscription "{SubscriptionId}"

// Using the list command and query argument you can obtain the name and location of your soft deleted APIM Instances

az apim deletedservice list --query "[].[name, location]"

// Since you now know the name and location of all the potential instances you wish to purge, you can now issue the purge command for each instance.

az apim deletedservice purge --service-name "{APIMInstanceName}" --location "{RegionDeployedTo}"

Rest API

In-order to purge a soft-deleted APIM instance, you will need to execute the Delete REST API for API Management as per Microsoft Documentation.

To make this simpler, here is some PowerShell using the 2021-08-01 REST API version and az tooling:

$SubscriptionId = '{SubscriptionId}'
$Region = '{Region}'
$APIMInstanceName = '{APIMInstanceName}'

Connect-AzAccount -Subscription $SubscriptionId

$accessToken = Get-AzAccessToken

$request = @{
    Method = 'DELETE'
    Uri = "$($SubscriptionId)/providers/Microsoft.ApiManagement/locations/$($Region)/deletedservices/$($APIMInstanceName)?api-version=2021-08-01"
    Headers = @{
        Authorization = "Bearer $($accessToken.Token)"

Invoke-RestMethod @request