Skip to main content
Custom roles are available when enabled for your account. Contact support to enable them.
Managing localization permissions for users are detailed in the Team management article.
Custom roles and permissions overview ButterCMS provides for the ability to fine-tune user roles and permissions on a granular level. With the custom roles and permissions features, you can:
  • assign the ability to perform admin actions, like managing users or updating schema configuration
  • restrict users to only specific CRUD operations, such as viewing, creating/cloning, publishing, etc.
  • restrict users to a specific global content type (such as all Page Types or all Collections)
  • restrict users to a specific Page Type or a specific Collection
  • any combination of the above

​
Creating a custom role

When creating a custom role, any permission not explicitly granted will be denied. Make sure you give the role all of the permissions necessary to perform its job functions!
1

Open Manage Roles

Go to Manage Roles and click Add Role.Add Role button in the Manage Roles tab
2

Name the role

Name the role and optionally mark it as Admin. Admin users will be able to manage schemas, organization settings, and users.
3

Add a permission

Click Add permission and choose an action, such as View or Create/Clone. Permission action selection
4

Select the content type

Select the overarching content type (Blog posts, Page Types, or Collections) the permission should apply to. If you only want to restrict users to a specific Page or Collection, use the dropdown to select it. Selecting specific page types for permissions Note that if you want to add multiple Page Types or Collections, just repeat the process to add another permission. Permission action selection

​
Permission actions

ActionWhat It Allows
All actionsCreate, edit, publish, and delete
ViewRead‑only access
Create/CloneCreate or duplicate content
Edit draftsModify unpublished content
Publish/UnpublishControl what goes live
DeletePermanently remove content
Admin settings (locales, users, webhooks) require the Admin toggle.

​
Permission priority

When a user has multiple roles or complex permissions:
  • More specific permissions override general ones
  • Explicit “no access” takes precedence over granted access
  • View permissions are cumulative (can see all granted content)

​
Permission limitations

ButterCMS permissions work at the content type level, not the individual field level. This means that permissions can’t control individual field visibility within a Page Type or Collection, or access to specific media library folders. For example, if a user has access to “Product Page” type, they can see all fields in the Product pages.

​
Example permission configurations

Role: Marketing Content Editor
Permission Configuration:
├── Action: All actions
├── Content Type: Page Types
└── Specific Page Type: Landing Page

Result: User can view, create, edit, publish, and delete
        only "Landing Page" type pages

Role: Product Catalog Manager
Permissions:
├── All actions → Collections → Products
├── All actions → Collections → Product Categories
├── View → Collections → Pricing Tiers
└── No access → Collections → Internal Notes

Result: User has full control over product content
        but can only view pricing (not edit)
        and cannot see internal notes at all

Role: Blog Writer
├── Create/Clone → Blog posts
└── Edit drafts → Blog posts

Role: Blog Editor
├── View → Blog posts
├── Edit drafts → Blog posts
└── Publish/Unpublish → Blog posts

Role: Blog Manager
└── All actions → Blog posts

Role: Senior Content Editor

Permissions:
1. All actions → Blog posts
   (Full control over blog content)

2. All actions → Page Types → Landing Page
   (Full control over landing pages)

3. Edit drafts → Page Types → Product Page
   (Can edit but not publish product pages)

4. View → Collections → Pricing
   (Can see but not edit pricing data)

5. All actions → Collections → Testimonials
   (Full control over testimonials)