Edit

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's scheduled to change, or depend on a version that's scheduled to retire. This article explains how to determine which API version you use and how to move to a current, supported version.

Important

All 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. This retirement doesn't affect data plane APIs.

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 ({YYYY}-{MM}-{DD}) https://management.azure.com
Data plane Objects inside a vault: keys, secrets, and certificates, and cryptographic operations. Version number (7.x) https://<vault-name>.vault.azure.net

The two surfaces version and retire on separate schedules. Updating one doesn't update the other. Review both if your workload uses both.

Why move to a current API version

  • Avoid retirement. Update control plane clients, templates, and REST calls before the retirement date. For more information, see Prepare for Key Vault API version 2026-02-01 and later.
  • Stay supported. Preview API versions are for early testing only, and Azure support SLAs don't cover them. Use the latest stable version for production workloads. Azure is deprecating preview control plane versions (except 2026-04-01-preview) with a 90-day notice period.
  • Get new features and fixes. New capabilities and behavior changes ship in newer API versions. For example, control plane API version 2026-02-01 introduces Azure RBAC as the default access control model for newly created vaults.

For the full list of supported control plane API versions, see Supported control plane API versions.

Current API versions

API surface Latest stable version
Control plane 2026-02-01
Data plane 7.6

Determine which API version you use

You specify the API version differently depending on how you call Key Vault. Check each surface your workload uses.

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=2026-02-01.
  • ARM, Bicep, and Terraform templates: 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'.
  • Control plane management SDKs: Your SDK package version determines the API version (for example, Azure.ResourceManager.KeyVault for .NET or azure-mgmt-keyvault for Python). Check the package version in your project's dependency manifest.
  • 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 Cloud Shell: Cloud Shell always uses the latest API version. If you run scripts in Cloud Shell, ensure they're compatible with control plane API version 2026-02-01 or later.

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=7.6.
  • Data plane SDKs: Your SDK package version determines the API version (for example, Azure.Security.KeyVault.Secrets, Azure.Security.KeyVault.Keys, or Azure.Security.KeyVault.Certificates). Check the package version in your project's dependency manifest.

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, Terraform) or the api-version query string parameter (REST) to 2026-02-01 or later in all Microsoft.KeyVault/vaults definitions and management requests.

  2. Update your control plane management SDKs. Control plane management SDKs that use older API versions stop working when those API versions retire on February 27, 2027. Upgrade to a package version that supports API version 2026-02-01 or later. For the required package versions per language, see Control plane SDK releases.

    Note

    The control plane retirement doesn't affect data plane SDKs. You only need to update control plane management SDKs for that change.

  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. API version 2026-02-01 and later change the default access control model for newly created vaults to Azure RBAC. This change affects only create operations. Existing vaults keep their current access model. Review the details and decide your path in Prepare for Key Vault API version 2026-02-01 and later.

Update the data plane API version

  1. Update the API version in your REST calls. Set the api-version query string parameter to 7.6 on requests to your vault endpoint.

  2. Update your data plane SDKs. Upgrade the Azure.Security.KeyVault.* (or the equivalent for your language) packages to the latest stable version. For the client libraries per language, see Azure Key Vault client libraries.

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

Related content

  • Last updated on