# Why You Should Disable Key-Based Metadata Write Access in Azure Cosmos DB

- Link: https://laughingcloud.io/why-you-should-disable-key-based-metadata-write-access-in-azure-cosmos-db
- Published: 2026-05-21T21:41:46+05:30
- Author: Visitha

Securing Azure Cosmos DB is not only about protecting data inside containers. It
is also about controlling who can change the account’s metadata, such as databases,
containers, throughput, and indexing settings. Azure Cosmos DB provides a setting
called `disableKeyBasedMetadataWriteAccess` that helps lock down these changes and
shift control to Azure role-based access instead of account keys.

## What is key-based metadata write access?

Key-based metadata write access means a client using Cosmos DB account keys can 
perform write operations on metadata resources, not just read or write data. These
metadata operations include creating or updating databases and containers, changing
throughput, and updating indexing policies.

In other words, if this setting is not disabled, anyone or any application with 
the account key may be able to modify structural parts of the Cosmos DB account,
depending on how it connects. This is different from normal data plane access because
it affects the configuration of the database environment itself.

## Why is it important to disable it?

The main reason is security and governance. Account keys are shared secrets, and
if they are used to change metadata, it becomes harder to enforce least-privilege
access and harder to fully audit who made structural changes through Azure role 
assignments.

Microsoft specifically recommends disabling key-based metadata write access before
auditing control plane operations in Azure Cosmos DB. Once this setting is enabled,
changes to resources must happen through a user or identity that has the proper 
Azure role and credentials instead of simply possessing the account key.

This also helps reduce the risk of accidental or unauthorized changes from applications,
scripts, SDK clients, or third-party tools that are still using account keys. For
example, a script that holds the Cosmos DB key should not also be able to silently
change throughput or indexing settings unless that is explicitly intended.

## What changes when you disable it?

After `disableKeyBasedMetadataWriteAccess` is set to `true`, SDK-based clients using
account keys can no longer perform metadata write operations. If they try to create
or update resources through the Cosmos DB endpoint, Azure Cosmos DB returns an error
indicating that the operation is not allowed through the endpoint.

This means the account keys continue to be unsuitable for metadata changes, while
administrative changes should be performed through Azure Resource Manager, Azure
CLI, Azure PowerShell, Azure portal, or templates using identities and Azure RBAC.

## How to disable key-based metadata write access

The setting is controlled at the Azure Cosmos DB account level by setting `disableKeyBasedMetadataWriteAccess`
to true.

Azure CLI,
az cosmosdb update \ –resource-group <resource-group> \ –name <account-
name> \ –disable-key-based-metadata-write-access true

## Best practice recommendation

For most production environments, disabling key-based metadata write access is a
strong security improvement because it separates application data access from administrative
resource changes. It also aligns better with Azure RBAC, governance, and auditing
practices.

A practical model is to let applications use only the permissions they need for 
data access, while reserving metadata and configuration changes for administrators,
DevOps pipelines, or platform automation that authenticate through Azure identities
and roles.

## Reference

[https://learn.microsoft.com/en-us/azure/cosmos-db/audit-control-plane-logs](https://learn.microsoft.com/en-us/azure/cosmos-db/audit-control-plane-logs)