Update the Azure Key Vault API version you use

Azure Key Vault uses versioned APIs. If your applications, scripts, or infrastructure templates call an older API version, you might miss newer features, use behavior that changed in a later version, or depend on a version that is no longer recommended. This article explains how to determine which API version you use and how to move to a current, supported version.

Important

All Key Vault control plane API versions before 2026-02-01 retire on February 27, 2027. After that date, your key vaults continue to exist, but you can manage them only with control plane API version 2026-02-01 or later. There's no exception or extension to this date. This retirement doesn't affect data plane APIs (the APIs used to work with keys, secrets, and certificates). For details, see Plan for Azure RBAC as the default access control model in Key Vault.

Azure Key Vault has two independent API surfaces, each with its own versions:

API surface What it manages Version scheme Example endpoint
Control plane (management) The key vault resource itself: create, update, delete vaults, and configure properties such as SKU, network rules, and access control. Date-based, such as 2026-02-01. Preview versions add a -preview suffix, such as 2026-03-01-preview. https://management.azure.com
Data plane Objects inside a vault: keys, secrets, and certificates, and cryptographic operations. Date-based, such as 2026-04-01, or numeric, such as 7.6. Preview versions add a suffix, such as 2026-03-01-preview or 7.6-preview.2. https://<vault-name>.vault.azure.net

The two surfaces have different versioning and lifecycle practices. Updating one doesn't update the other. Review both if your workload uses both.

Because both surfaces use date-based versions, a version string alone doesn't identify the surface. For example, both the control plane and the data plane have a 2026-03-01-preview version.

Control plane API versions can be retired, as described earlier in this article.

Preview data plane API versions can be deprecated, so don't use previews in production unless you accept that lifecycle. For supported data plane API versions, see the Azure Key Vault REST API reference.

This article focuses on identifying and updating API versions. Updating a control plane API version doesn't require you to migrate an existing key vault from access policies to Azure RBAC. If you want to migrate access control, see Migrate to Azure RBAC from access policies. For the Azure RBAC default behavior introduced for new key vaults in API version 2026-02-01 and later, see Plan for Azure RBAC as the default access control model in Key Vault.

Why move to a current API version

  • Use supported capabilities. Newer API versions can add capabilities, correct behavior, or support new service features.
  • Keep production workloads stable. Use a current stable API version for production workloads. Preview API versions are for evaluation and early testing, and Azure support SLAs might not cover them. Preview versions can be deprecated.
  • Keep tools and libraries compatible. Azure CLI, Azure PowerShell, SDKs, templates, and the portal can use different API versions. Updating the version for one client doesn't update the others.

For current control plane versions, see Supported control plane API versions. For supported data plane versions, see the Azure Key Vault REST API reference.

Identify affected API calls by using logs

A service notice doesn't necessarily mean that telemetry detected a retiring API version in every subscription or key vault you own. Notices can reach a broader audience than the resources detected in recent telemetry.

Use Key Vault audit logs to find which key vaults and operations used a retiring API version. Then find where your code, templates, or tools set that version, as described in Find API version references in your code and workflows, and update your API version.

Collect Key Vault audit logs

Send the audit logs for each key vault that you want to investigate to a Log Analytics workspace. For steps, see Enable Key Vault logging. To configure many key vaults at once, see Create diagnostic settings at scale by using built-in Azure Policy. Use one workspace for these key vaults so you can query them together.

Set up logging early. Logs include only requests made after the diagnostic setting takes effect, and earlier requests aren't backfilled. After you create a diagnostic setting, data can take up to 90 minutes to appear. For more information, see Expected latency after creating a diagnostic setting.

Audit events include both control plane and data plane operations, but this retirement affects only control plane operations.

The Azure Activity log doesn't record the API version of a request, so use Key Vault audit logs to find requests that use a retiring version.

To confirm that records are arriving, run the following query in your workspace. For more information about running queries, see Log Analytics tutorial.

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| order by TimeGenerated desc
| take 50

Check _ResourceId and TimeGenerated to confirm that records arrive from the intended key vaults. To check a key vault that isn't in the latest 50 rows, filter by _ResourceId before order by.

If a table is missing or the query returns no records, recheck the workspace, the saved diagnostic setting, the source key vault, the query scope, the time range, and your permissions. If your diagnostic setting sends logs to resource-specific tables, query the AZKVAuditLogs table instead, as described at the end of the next section.

Find requests that use a retiring API version

Important

Logs include only the requests that a key vault receives while its diagnostic setting is active, and only within the time range that you query. If your queries return no matching requests, that doesn't mean you're unaffected. For example, logs don't show the requests that created key vaults years ago, even if the templates or scripts that created those key vaults still specify a retiring version. Always review your application code, deployment templates, automation scripts, and other workflows for references to a retiring API version.

The following queries return only control plane requests by filtering on the Azure Resource Manager endpoint in the request URI. Data plane requests go to your vault endpoint instead, such as https://<vault-name>.vault.azure.net. The queries use the endpoint for Azure public cloud. For other clouds, replace https://management.azure.com/ with the endpoint for your cloud:

Cloud Azure Resource Manager endpoint
Azure public cloud https://management.azure.com/
Azure Government https://management.usgovcloudapi.net/
Azure operated by 21Vianet https://management.chinacloudapi.cn/

Other clouds use their own Azure Resource Manager endpoint.

The queries filter on the endpoint because some data plane API versions use the same date-based format as control plane versions. For example, the data plane also has a 2026-03-01-preview version. For the operation names that Key Vault logs, see Operation names table.

To list the key vaults that received control plane requests with an API version earlier than 2026-02-01, run the following query. It returns one row for each key vault and API version, with the number of requests, the most recent request, and the requested operations.

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc

To investigate individual requests, use one of the following queries.

To find requests that use a specific retiring version, such as 2026-03-01-preview, filter on that version:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where OperationVersion == "2026-03-01-preview"
| order by TimeGenerated desc

To find requests that use any control plane API version earlier than 2026-02-01, filter on versions that sort before 2026-02-01:

AzureDiagnostics
| where TimeGenerated >= ago(30d)
| where ResourceProvider =~ "MICROSOFT.KEYVAULT"
| where Category == "AuditEvent"
| where requestUri_s startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| order by TimeGenerated desc

The queries in this article use the AzureDiagnostics table, which receives Key Vault audit logs when the diagnostic setting's destination table is Azure diagnostics. If the destination table is Resource specific, audit logs go to the AZKVAuditLogs table instead. In that case, adjust each query in this article, including the collection check: replace AzureDiagnostics with AZKVAuditLogs, remove the ResourceProvider and Category filters, and replace requestUri_s with RequestUri. For example, the affected key vaults query becomes:

AZKVAuditLogs
| where TimeGenerated >= ago(30d)
| where RequestUri startswith "https://management.azure.com/"
| where strcmp(OperationVersion, "2026-02-01") < 0
| summarize Requests = count(), LastSeen = max(TimeGenerated), Operations = make_set(OperationName) by _ResourceId, OperationVersion
| order by Requests desc

Don't filter on operation names that start with Vault, because that filter can exclude recorded child resource operations. Use OperationName and the request URI to understand which management operation occurred. Use the details in these logs to identify the caller. Then find where the caller sets the API version, as described in the next section, and update it as described in Update your API version.

Find API version references in your code and workflows

Where you set the API version depends on how you call Key Vault. Check each method that your workload uses, even if your logs show no requests from it.

Control plane (management)

  • REST API: The version is the api-version query string parameter on requests to https://management.azure.com, for example ?api-version=<control-plane-version>.
  • ARM templates and Bicep files: The version is the apiVersion property on each Microsoft.KeyVault/vaults resource. In Bicep, it's part of the resource type declaration, for example resource kv 'Microsoft.KeyVault/vaults@2026-02-01'. Child resources such as Microsoft.KeyVault/vaults/secrets, Microsoft.KeyVault/vaults/keys, and Microsoft.KeyVault/vaults/accessPolicies are also control plane resources, and each declares its own API version. Updating the parent vault's version doesn't update its child resources.
  • Terraform: With the AzAPI provider, the version is part of the resource type, for example Microsoft.KeyVault/vaults@2026-02-01. With the AzureRM provider, the provider version determines the API version, and resources don't have an API version setting. Check the provider release notes and resource documentation for the API version that your provider version uses.
  • Control plane management SDKs: The package version can determine which API versions an SDK supports, but the package version alone doesn't always identify the API version used by a request. Check the package release notes and API reference (for example, for Azure.ResourceManager.KeyVault or azure-mgmt-keyvault) and compare them with the package version in your project's dependency manifest. For API references by language, see Azure Key Vault client libraries.
  • Azure CLI and Azure PowerShell: The version of your Azure CLI or Az module determines the API version. Check your installed version with az version or Get-InstalledModule -Name Az.
  • Azure portal: The portal selects the control plane API version for its requests. You can't set that version directly. The portal uses API version 2026-02-01, so portal operations don't use a retiring version. The portal can use a different API version than your templates, scripts, or SDKs, so don't use portal behavior to determine the version used by your automation.
  • Azure Cloud Shell: Cloud Shell uses current Azure CLI and Azure PowerShell versions. If you run scripts in Cloud Shell, ensure they're compatible with the currently supported control plane API version.

Data plane

  • REST API: The version is the api-version query string parameter on requests to your vault endpoint, for example GET https://<vault-name>.vault.azure.net/secrets/<name>?api-version=<data-plane-version>.
  • Data plane SDKs: The package version can determine which API versions an SDK supports, but the package version alone doesn't always identify the API version used by a request. Check the package release notes and API reference (for example, for Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keys, or Azure.Security.KeyVault.Certificates) and compare them with the package version in your project's dependency manifest. For API references by language, see Azure Key Vault client libraries.

Update your API version

Update the control plane API version

  1. Update the API version in your templates and REST calls. Set apiVersion (ARM, Bicep), the versioned resource type (Terraform AzAPI), or the api-version query string parameter (REST) to a currently supported control plane version. Update all Microsoft.KeyVault/vaults definitions, their child resources, and management requests. If you use the Terraform AzureRM provider, update the provider to a version that uses a supported control plane API version.

  2. Update your control plane management SDKs. Check the package release notes and API reference for the package version that supports the control plane API version you selected. For API references by language and the package versions that support the current Key Vault control plane version, see Azure Key Vault client libraries and Control plane SDK releases.

    Note

    Updating a control plane management SDK doesn't update data plane SDKs. Update each SDK separately if your application uses both API surfaces.

  3. Update Azure CLI and Azure PowerShell. Newer tool versions call newer API versions.

    Update the Azure CLI to the latest version. For more information, see How to update the Azure CLI.


  1. Review behavior changes before you deploy. Read the API version's change log and specification before you deploy. API version 2026-02-01 and later changes the default access-control model only for new key vaults. For details, see Plan for Azure RBAC as the default access control model in Key Vault.

Update the data plane API version

  1. Update the API version in your REST calls. Set the api-version query string parameter to a currently supported data plane version listed in the Azure Key Vault REST API reference.

  2. Update your data plane SDKs. Upgrade the Azure.Security.KeyVault.* (or the equivalent for your language) packages to a current stable version. Check the package release notes and API reference to determine which data plane API versions the package supports. For API references and package links by language, see Azure Key Vault client libraries.

Stable data plane API versions aren't affected by the current control plane retirement. If you use a preview data plane API, review the service announcements and the API reference for its lifecycle.

For more information about calling the data plane REST API, see Authentication, requests, and responses and the Azure Key Vault REST API reference.