Blog Post

Azure Integration Services Blog
5 MIN READ

Rotating credentials in Azure API Management

vladvino's avatar
vladvino
Icon for Microsoft rankMicrosoft
Nov 21, 2026

This guide explains how to find and rotate the secrets and credentials configured in your Azure API Management instances. It includes example Azure CLI operations and links to public documentation. Test every command in a non-production instance first.

Credentials covered by this guidance

  • Subscription keys
  • Named values that contain secrets
  • Backend credentials (headers, query parameters, client certificates)
  • OAuth 2.0 and OpenID Connect client secrets
  • Connection strings (for example, Event Hubs loggers)
  • Credentials written directly into policies

How to rotate safely

Use this order when both credentials can remain valid:

  1. Create a new secret where it is issued.
  2. Update API Management with the new secret.
  3. Test your APIs.
  4. Revoke the old secret.

Important: Rotate each credential where it is issued (for example, the backend service or identity provider), not only in API Management. Updating the value in API Management alone does not invalidate the old credential.

Find your instances and credentials

Step 1: List your API Management instances

In the Azure portal, search for API Management services, or use Azure CLI:

In one subscription:

az apim list --subscription {subscriptionId} --query "[].{name:name, resourceGroup:resourceGroup}" --output table

Across accessible subscriptions (one Azure Resource Graph page):

az graph query -q "resources | where type =~ 'microsoft.apimanagement/service' | project name, resourceGroup, subscriptionId, location"

Step 2: List the credentials in each instance

In the commands, replace {base} with https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{apimName}, and the other values in braces with your own. In policies, look for values such as Authorization headers, keys, passwords, tokens or connection strings written out in full instead of referenced as a named value.

Subscription keys are under APIs > Subscriptions in the Azure portal.

az rest --method get --url "{base}/subscriptions?api-version=2024-05-01"

Named values are under APIs > Named values. The Type column shows whether each secret is stored in API Management or in Key Vault.

az apim nv list --resource-group {rg} --service-name {apimName} --output table

Backend credentials are under APIs > Backends > Authorization credentials.

az rest --method get --url "{base}/backends?api-version=2024-05-01"

OAuth 2.0 and OpenID Connect providers are under Developer portal > OAuth 2.0 + OpenID Connect. Developer portal sign-in providers are under Developer portal > Identities.

az rest --method get --url "{base}/authorizationServers?api-version=2024-05-01"
az rest --method get --url "{base}/openidConnectProviders?api-version=2024-05-01"
az rest --method get --url "{base}/identityProviders?api-version=2024-05-01"

List providers under APIs > Credential manager:

az rest --method get --url "{base}/authorizationProviders?api-version=2024-05-01"

Loggers that use connection strings (Event Hubs, Application Insights):

az rest --method get --url "{base}/loggers?api-version=2024-05-01"

Check global, API, and operation policies under Design. For product policies, select Products > the product > Policies.

az rest --method get --url "{base}/policies/policy?format=rawxml&api-version=2024-05-01"
az rest --method get --url "{base}/apis/{apiId}/policies/policy?format=rawxml&api-version=2024-05-01"

Step 3: Read the current secret values

Read each secret to identify which systems use it before you rotate it. This requires permission to read secrets on the instance. Store the output securely and delete it when you are finished.

az rest --method post --url "{base}/subscriptions/{sid}/listSecrets?api-version=2024-05-01"
az apim nv show-secret --resource-group {rg} --service-name {apimName} --named-value-id {namedValueId}
az rest --method post --url "{base}/authorizationServers/{id}/listSecrets?api-version=2024-05-01"
az rest --method post --url "{base}/openidConnectProviders/{id}/listSecrets?api-version=2024-05-01"
az rest --method post --url "{base}/identityProviders/{id}/listSecrets?api-version=2024-05-01"
az rest --method post --url "{base}/tenant/access/listSecrets?api-version=2024-05-01"

Rotate each credential type

The commands below use the same {base} placeholder as in Step 2. Replace the other values in braces with your own.

Subscription keys

Move callers to the secondary key, regenerate the primary key, move callers to the new primary key, then regenerate the secondary key.

az rest --method post --url "{base}/subscriptions/{sid}/regeneratePrimaryKey?api-version=2024-05-01"
az rest --method post --url "{base}/subscriptions/{sid}/regenerateSecondaryKey?api-version=2024-05-01"

For additional details, see Subscriptions in Azure API Management.

Named values

If the named value is backed by Key Vault, store the replacement in Key Vault, point any pinned reference to the new version, and refresh the named value. If the secret is stored in API Management, update the value with a new credential and consider moving it to Key Vault.

az rest --method post --url "{base}/namedValues/{namedValueId}/refreshSecret?api-version=2024-05-01"
az apim nv update --resource-group {rg} --service-name {apimName} --named-value-id {namedValueId} --value "{newValue}"

For additional details, see Use named values in Azure API Management policies.

Backend credentials

Stage the replacement at the backend. Update and test API Management before revoking the old credential. Example for a backend with only one credential, using its current ETag:

az rest --method patch --url "{base}/backends/{backendId}?api-version=2024-05-01" --headers 'If-Match={etag}' --body '{"properties":{"credentials":{"header":{"{headerName}":["{newKey}"]}}}}'

For additional details, see Backends in API Management.

OAuth 2.0 and OpenID Connect client secrets

Create the secret at its issuer. Update API Management, republish the portal if used, and test before deleting the old secret. For Microsoft Entra ID:

az ad app credential reset --id {appId} --append --display-name "apim-rotation"
az ad app credential delete --id {appId} --key-id {oldKeyId}

For additional details, see Add and manage application credentials in Microsoft Entra ID.

Connection strings

For Event Hubs, switch the logger to the secondary connection string and test delivery before renewing the namespace rule’s primary key:

az eventhubs namespace authorization-rule keys renew --resource-group {rg} --namespace-name {namespace} --name {ruleName} --key PrimaryKey

For additional details, see How to log events to Azure Event Hubs in Azure API Management.

Credentials in policies

Create the replacement at the source. Reference its Key Vault-backed named value as {{display-name}}. Test the policy before revoking the old credential.

For additional details, see Use named values in Azure API Management policies.

Management API access keys

For legacy Direct Management API keys, switch callers off each key before regenerating it.

az rest --method post --url "{base}/tenant/access/regeneratePrimaryKey?api-version=2024-05-01"
az rest --method post --url "{base}/tenant/access/regenerateSecondaryKey?api-version=2024-05-01"

For additional details, see Tenant Access - Regenerate Primary Key.

Best practices going forward

  • Use managed identities instead of keys and connection strings wherever supported.
  • Store secrets in Azure Key Vault and reference them as named values. Use a secret identifier without a version for automatic refresh.
  • Rotate credentials regularly and automate rotation where possible.
  • Review your configuration for subscriptions, users, policies or backends that you did not create.

Additional documentation

Published Nov 21, 2026
Version 1.0
No CommentsBe the first to comment