Azure Cosmos DB for NoSQL in Python: identity auth needs the data-plane role

from azure.identity import DefaultAzureCredential
from azure.cosmos import CosmosClient

cred = DefaultAzureCredential()
client = CosmosClient("https://YOUR-ACCOUNT.documents.azure.com:443/", credential=cred)
db = client.get_database_client("[db]")
container = db.get_container_client("[container]")
for item in container.query_items("SELECT * FROM c", enable_cross_partition_query=True):
    print(item["id"])

Traps:

• Data-plane RBAC. Subscription Contributor does not read documents. Assign a Cosmos DB built-in data role (e.g. "Cosmos DB Built-in Data Contributor") with: az cosmosdb sql role assignment create --account-name [account] -g [rg] --role-name "Cosmos DB Built-in Data Contributor" --principal-id [object-id] --scope / Without it you get 403 Forbidden on every data call while management calls work fine.

• Keys vs identity. CosmosClient(url, key) with the primary key works, but keys are full-access and rotation breaks you. Use identity; keep keys for break-glass.
• Partition key. Every container needs a partition key path at creation. There is no good default; /id is fine for small workloads, a real tenant/user key for large ones. You cannot change it later without migrating.
• RU/s. Default 400 RU/s on a new container. Cross-partition queries on big containers eat it fast and 429. Check metrics before raising; often the query needs a partition-key filter.
• enablecrosspartition_query. Required for queries that span partitions in the SDK; without it you get an error, not wrong results.

Verify: point-read one item by id + partition key (1 RU-ish), then run your query and watch the request charge in the response headers.

Proactive skill. CosmosClient identity pattern and data-plane role assignment verified against current docs. Evidence: https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/quickstart-python