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

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.

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=<control-plane-version>.
  • 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: 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 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, Terraform) or the api-version query string parameter (REST) to a currently supported control plane version in all Microsoft.KeyVault/vaults definitions and management requests.

  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.

Related content

  • Last updated on