How to Configure Cosmos DB Grant Permissions
You set up cosmos db grant permissions by assigning identity roles to your database account. These roles split access between account settings and actual stored data. Many teams start by sharing account keys across apps and users. Shared keys give broad rights to read, change, or delete any container. When one key leaks, every table and item in that account faces risk. How cosmos db grant permissions work in practice Azure splits database access into a control plane and a data plane. Control
Your coding agents run with your access.
Claude Code reaches prod with a developer's credentials, and approval prompts get clicked through. hoop.dev checks every query, masks sensitive data, and holds risky changes for a human.
You set up cosmos db grant permissions by assigning identity roles to your database account. These roles split access between account settings and actual stored data. Many teams start by sharing account keys across apps and users. Shared keys give broad rights to read, change, or delete any container. When one key leaks, every table and item in that account faces risk.
How cosmos db grant permissions work in practice
Azure splits database access into a control plane and a data plane. Control plane roles let admins create accounts, change regions, and manage firewall rules. Data plane roles control who can read, write, or delete items inside containers. You must pick the right plane before you assign a role to a user.
For the data plane, the platform offers built-in read-only and read-write role definitions. You can also build custom role definitions that list allowed data actions. Once you define a role, you link it to a user or app identity. You also set a scope for that assignment, like an account, database, or container.
If your account uses a MongoDB or Postgres API, permissions work a bit differently. In those modes, you can also create native database users and roles inside the engine. Standard SQL API accounts rely on Azure identity tokens or master keys instead. Identity roles are safer than master keys because they tie actions to one user.
Choosing the right scope for database roles
Scope determines how far a role reaches inside your database account. An account scope applies the role to every database and container you own. A database scope limits the user to one database and its child containers. A container scope restricts the user to a single collection of items.
Good security starts with the narrowest scope that still lets the worker finish the job. Give an app access only to the specific containers it reads or writes. Avoid assigning account-level write roles to engineers who only check production bugs. Smaller scopes reduce the blast radius when someone makes a mistake during a shift.
Still, managing many container-level assignments across dozens of engineers takes time. Teams often group users into directory groups and assign roles to the group instead. Group assignments make onboarding faster, but they often result in permanent standing access. People keep those group roles long after they finish their debugging task.
AI Agent Permissions + End-to-End Encryption: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What native roles solve and where gaps remain
Native role assignments solve the basic problem of who can log in. They replace shared master keys with tracked user and app identities. They also block unauthorized users from deleting accounts or changing network rules. For service-to-service traffic, native roles work well and keep apps running.
Still, native roles only check permissions at the container or database level. Once a user has read rights on a container, they can read every field. The database does not redact sensitive fields like emails, phone numbers, or card numbers. A support engineer checking one bad record can also query every customer item.
Native roles also do not inspect individual queries or commands before they run. A developer with write rights can run a bad script that updates thousands of items. Standing roles stay active all day, even when no ticket requires database work. Teams need query-level checks and field masking to close this daily operational gap.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev sits inline in the protocol beside each supported service as an open-source proxy, a sidecar for your database or API. For every query or command an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human approval.
First, hoop.dev guardrails block banned queries before they run or hold risky ones for review, and hoop.dev data masking rewrites matched sensitive values in responses in memory. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
What is the difference between control plane and data plane roles?
Control plane roles manage the Azure resource, like network settings, backups, and scaling rules. Data plane roles control who can read, write, or delete items inside your containers.
Should my team use master keys or identity roles for human access?
Always use identity roles for human access instead of shared master keys. Identity roles tie actions to a single person and let you limit scope per container.
Can native data plane roles hide sensitive fields inside a document?
No, native data plane roles grant read access to the whole item in a container. To mask fields like emails or card numbers in results, you need query-level masking.
Related guides
In this post