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.