ButterCMS Roles and Permissions Guide

ButterCMS team roles -- Admin, Publisher, Author, and Viewer permissions with API token management for headless content delivery.

ButterCMS is a headless CMS with a role-based team management system. Since it is API-first, permissions affect both the dashboard UI and API access.

ButterCMS Role Model

Role	Manage Team	Manage Settings	Create Content	Publish Content	View Content	API Access
Admin	Yes	Yes	Yes	Yes	Yes	Full
Publisher	No	No	Yes	Yes	Yes	Read/Write
Author	No	No	Yes	No (needs approval)	Yes	Read
Viewer	No	No	No	No	Yes	Read

Admin

Full control over the ButterCMS project including team management, API token configuration, webhooks, and all content operations.

Publisher

Can create and publish content directly. Cannot manage team members or project settings.

Author

Can create content but cannot publish directly. Content enters a review queue for Publishers/Admins to approve.

Viewer

Read-only access to all content. Useful for stakeholders or developers who need to see content without editing.

API Token Scopes

ButterCMS uses two types of API tokens:

# Read API Token (safe for client-side use)
# Used for fetching published content
curl "https://api.buttercms.com/v2/posts/?auth_token=YOUR_READ_TOKEN"

# Write API Token (server-side only)
# Used for creating/updating content programmatically
curl -X POST "https://api.buttercms.com/v2/posts/" \
  -H "Authorization: Token YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Post", "body": "<p>Content</p>"}'

Token Type	Read Content	Write Content	Manage Settings	Manage Users
Read Token	Yes	No	No	No
Write Token	Yes	Yes	No	No

Analytics-Relevant Permissions

Since ButterCMS is headless, analytics scripts are added in your frontend application, not in ButterCMS itself. However, ButterCMS webhooks can notify your analytics pipeline of content changes:

// Webhook payload for content publish events
// Configure at Dashboard > Settings > Webhooks
{
  "data": {
    "id": "post-slug",
    "type": "blog_post",
    "status": "published"
  },
  "webhook_event": "post.published"
}

Custom Roles

ButterCMS does not support custom roles beyond the four built-in roles. For fine-grained access, use separate ButterCMS projects with different team assignments.

Best Practices

Use Read tokens on client-side and Write tokens only on server-side
Assign Author role to content creators and Publisher to content managers
Rotate API tokens quarterly and store them in environment variables
Set up webhooks to trigger analytics pipeline updates on content changes
Keep Admin accounts limited to project owners and technical leads

शीर्ष पर वापस जाएँ