> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # Configure Custom Database Roles You can create custom roles in Atlas when the [built-in roles](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-atlas-user-privileges) don't include your desired set of privileges. Atlas applies each database user's custom roles together with: - Any [built-in roles](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-atlas-user-privileges) you assign when you [add a database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-add-mongodb-users) or [modify a database user.](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-modify-mongodb-users) - Any [specific privileges](https://www.mongodb.com/docs/manual/reference/privilege-actions/) you assign when you [add a database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-add-mongodb-users) or [modify a database user.](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-modify-mongodb-users) You can assign multiple custom roles to each database user. **Note: Free Cluster and Flex cluster Limitation** Changes to [custom roles](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles.md#std-label-mongodb-roles) might take up to 30 seconds to deploy in Free clusters and Flex clusters. The [privilege actions](https://www.mongodb.com/docs/manual/reference/privilege-actions/) available for [custom roles](https://www.mongodb.com/docs/atlas/security-add-mongodb-roles.md#std-label-mongodb-roles) and the [custom roles API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-custom-database-roles) represent a subset of the privilege actions available for [built-in roles.](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#std-label-atlas-user-privileges) To review the list of custom role privileges, see the [API reference.](https://www.mongodb.com/docs/atlas/reference/custom-role-actions.md#std-label-custom-role-api-enum) ## Considerations **Important:** You must use the [Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-customDbRoles-create/), [Atlas Administration API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-database-users), Atlas UI, or a supported [integration](https://www.mongodb.com/docs/atlas/partner-integrations.md#std-label-partner-integrations) to add, modify, or delete database roles on Atlas clusters. Otherwise, Atlas rolls back any role modifications. - You can assign up to 20 custom roles to a single [database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users) - You can create up to 100 custom roles per project by default. IMPORTANT: If you require more custom roles per project, you can increase the number of custom roles up to a maximum of 1400 through the Atlas Administration API using the [Set One Project Limit endpoint.](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Projects/operation/setProjectLimit) - Atlas audits the creation, deletion, and updates of custom MongoDB roles in the project's [Activity Feed.](https://www.mongodb.com/docs/atlas/tutorial/activity-feed.md#std-label-view-activity-feed) - If you assign multiple roles to a user and those roles grant conflicting permissions for an object, Atlas honors the highest permissions within any role. For example: You create two custom roles and assign both to User A: - The first custom role grants only `read` privileges on your database. It also grants [bypassDocumentValidation](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-bypassDocumentValidation) on your database. - The second role grants `dbAdmin` privileges on your database. It doesn't grant [bypassDocumentValidation](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-bypassDocumentValidation), which is an implicit denial of bypass permissions. User A would have all of the `dbAdmin` privileges for your database, since `dbAdmin` is the higher database access permission. User A would also have [bypassDocumentValidation](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-bypassDocumentValidation), since [bypassDocumentValidation](https://www.mongodb.com/docs/manual/reference/privilege-actions/#mongodb-authaction-bypassDocumentValidation) is the higher bypass permission. ## Required Access To configure custom database roles, you must have [`Organization Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Organization-Owner), [`Project Owner`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Owner), or [`Project Database Access Admin`](https://www.mongodb.com/docs/atlas/reference/user-roles.md#mongodb-authrole-Project-Database-Access-Admin) access to Atlas. ## Add Custom Roles ### Atlas CLI To create a custom database role for your project using the Atlas CLI, run the following command: ```sh atlas customDbRoles create [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas customDbRoles create.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-customDbRoles-create/) ## View Custom Roles ### Atlas CLI To list all custom database roles for your project using the Atlas CLI, run the following command: ```sh atlas customDbRoles list [options] ``` To return the details for a single custom database role in the project you specify using the Atlas CLI, run the following command: ```sh atlas customDbRoles describe [options] ``` To learn more about the syntax and parameters for the previous commands, see the Atlas CLI documentation for [atlas customDbRoles list](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-customDbRoles-list/) and [atlas customDbRoles describe.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-customDbRoles-describe/) **See also: Related Links** - [Install the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/install-atlas-cli/) - [Connect to the Atlas CLI](https://www.mongodb.com/docs/atlas/cli/current/connect-atlas-cli/) ## Modify Custom Roles ### Atlas CLI To update a custom database role for your project using the Atlas CLI, run the following command: ```sh atlas customDbRoles update [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas customDbRoles update.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-customDbRoles-update/) ## Delete Custom Roles ### Atlas CLI To delete a custom database role from your project using the Atlas CLI, run the following command: ```sh atlas customDbRoles delete [options] ``` To learn more about the command syntax and parameters, see the Atlas CLI documentation for [atlas customDbRoles delete.](https://www.mongodb.com/docs/atlas/cli/current/command/atlas-customDbRoles-delete/) You cannot delete a custom role in the following scenarios: - When deleting the role would leave one or more child roles with no parent roles or actions. - When deleting the role would leave one or more [database users](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-users) with no roles. ## Assign Custom Roles You can assign custom roles in the Atlas UI when you [add a database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-add-mongodb-users) or [modify a database user](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-modify-mongodb-users). To assign custom roles through the Atlas Administration API, see [Create a Database User](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-creategroupdatabaseuser) or [Update a Database User.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-updategroupdatabaseuser)