Docs Menu
Docs Home
MongoDB Atlas
/ /

Configure Custom Database Roles

On this page

  • Considerations
  • Required Access
  • Add Custom Roles
  • View Custom Roles
  • Modify Custom Roles
  • Delete Custom Roles
  • Assign Custom Roles

You can create custom roles in Atlas when the built-in roles don't include your desired set of privileges. Atlas applies each database user's custom roles together with:

  • Any built-in roles you assign when you add a database user or modify a database user.

  • Any specific privileges you assign when you add a database user or modify a database user.

You can assign multiple custom roles to each database user.


Free Cluster, Shared Cluster, and Serverless Instance Limitation

Changes to custom roles might take up to 30 seconds to deploy in M0 free clusters, M2/M5 shared clusters, and serverless instances.

The privilege actions available for custom roles and the custom roles API represent a subset of the privilege actions available for built-in roles.

To review the list of custom role privileges, see the API reference.


You must use the Atlas CLI, Atlas Administration API, Atlas UI, or a supported integration 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 and can create up to 100 custom roles per project. If you require more custom roles per database user or per project, contact Atlas support.

  • Atlas audits the creation, deletion, and updates of custom MongoDB roles in the project's 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.


    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 on your database.

    • The second role grants dbAdmin privileges on your database. It doesn't grant 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, since bypassDocumentValidation is the higher bypass permission.

To configure custom database roles, you must have Organization Owner or Project Owner access to Atlas.

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 with no roles.

You can assign custom roles in the Atlas UI when you add a database user or modify a database user. To assign custom roles through the Atlas Administration API, see Create a Database User or Update a Database User.

← Built-In Roles and Privileges