Buttercms User Management: Roles and Permissions

This section covers user management, roles, and permissions for ButterCMS and associated analytics tools. ButterCMS is a headless CMS and blogging platform that provides content infrastructure for websites and applications through APIs.

Overview

ButterCMS provides comprehensive user management capabilities designed for development teams and content creators working with headless architecture. As a SaaS-based headless CMS, ButterCMS emphasizes API-first content delivery with robust access controls for team collaboration.

User management in ButterCMS features:

• Cloud-based user administration through the dashboard
• Role-based access control with customizable permissions
• API token management for secure programmatic access
• Team workspaces for organizing users and content
• Audit logging for tracking user activities
• SSO support for enterprise authentication (higher-tier plans)

ButterCMS is ideal for modern web applications, headless websites, and multi-channel content delivery requiring developer-friendly APIs and flexible content management.

Platform User Management

• Roles & Permissions - Understanding user roles
• Adding & Removing Users - User administration

Accessing User Management

To manage users in ButterCMS:

1. Log in to your ButterCMS dashboard at buttercms.com
2. Navigate to Settings in the left sidebar
3. Select Team Members or Users
4. View current users, roles, and permissions

User management capabilities depend on your subscription plan. Higher-tier plans offer more advanced features like SSO and custom roles.

ButterCMS User Roles

ButterCMS provides a flexible role system with default roles and custom role creation on enterprise plans:

Admin

Administrators have full control over the ButterCMS account:

• Complete access to all content and settings
• Can manage all users and team members
• Full billing and subscription control
• Can create, modify, and delete content types
• Access to all API tokens and webhooks
• Configure integrations and extensions
• View audit logs and analytics
• Can delete or archive the account

When to use: Assign to account owners and senior technical leads. Limit to 2-3 users.

Developer

Developers have technical access with some limitations:

• Can create and modify content types
• Full access to API tokens and documentation
• Can configure webhooks and integrations
• Cannot manage billing or subscriptions
• Cannot delete the account
• Can view but not modify user settings
• Full access to developer tools and documentation
• Can publish and unpublish content

When to use: Assign to software engineers and technical team members who integrate ButterCMS.

Editor

Editors focus on content management and publishing:

• Can create, edit, and publish all content
• Can upload and manage media files
• Can create content within existing content types
• Cannot modify content type schemas
• Cannot access API tokens or developer settings
• Cannot manage users or billing
• Can preview content before publishing
• Access to content scheduling features

When to use: Assign to content managers and editorial team members.

Writer

Writers have content creation permissions:

• Can create and edit their own content
• Can save drafts and submit for review
• Can upload media files for their content
• Cannot publish without approval (configurable)
• Cannot edit others' content
• Cannot modify content types or settings
• Limited to assigned content sections
• Can view published content

When to use: Assign to content creators and contributors who write but don't publish.

Reviewer

Reviewers manage content approval workflows:

• Can review and approve content submissions
• Can edit content from writers
• Can publish approved content
• Cannot create new content types
• Cannot manage users or settings
• Focus on quality control and approval
• Can schedule content publication

When to use: Assign to editors or managers responsible for content quality assurance.

Custom Roles and Permissions

Enterprise plans support custom role creation:

Creating Custom Roles

1. Navigate to Settings > Team > Roles
2. Click Create Custom Role
3. Define role name and description
4. Select specific permissions:
   • Content type access (per type)
   • Publishing permissions
   • Media library access
   • Settings access
5. Save the custom role
6. Assign to team members as needed

Granular Permissions

Available permission categories:

• Content Type Access: Per-content-type read/write/publish permissions
• Media Management: Upload, edit, delete media files
• Content Scheduling: Schedule and unschedule content
• Webhook Management: Create and modify webhooks
• API Token Access: View and create API tokens
• User Management: Invite and manage team members
• Billing Access: View and modify subscription

Adding and Inviting Users

Inviting Team Members

To add a user to ButterCMS:

1. Navigate to Settings > Team Members
2. Click Invite User or Add Team Member
3. Enter the user's email address
4. Select a role from the dropdown
5. Optionally set content-specific permissions
6. Click Send Invitation

The invitee receives an email with instructions to:

• Create a ButterCMS account (if new)
• Accept the team invitation
• Set up their profile and password

User Limits by Plan

Team member limits vary by subscription:

• Developer Plan: Up to 3 users
• Startup Plan: Up to 5 users
• Business Plan: Up to 10 users
• Enterprise Plan: Unlimited users

Removing Team Members

To remove a user:

1. Go to Settings > Team Members
2. Find the user to remove
3. Click the menu icon (⋮) next to their name
4. Select Remove from Team
5. Confirm the removal

Removed users immediately lose access. Their created content remains in the system.

API Token Management

ButterCMS uses API tokens for programmatic access:

API Token Types

Read Tokens:

• Public, read-only access to content
• Safe to use in client-side code
• Cannot modify or delete content
• Included in all plans

Write Tokens:

• Full API access including content creation
• Must be kept secret (server-side only)
• Can create, update, and delete content
• Available on higher-tier plans

Preview Tokens:

• Access to draft and scheduled content
• Used for content previews
• Read-only access to unpublished content

Managing API Tokens

To create and manage API tokens:

1. Navigate to Settings > API Tokens
2. View existing tokens and their permissions
3. Click Create Token for new tokens
4. Select token type and permissions
5. Copy and securely store the token
6. Revoke tokens when no longer needed

API Token Security

Best practices for token management:

1. Never Commit Tokens: Don't include in version control
2. Use Environment Variables: Store tokens in environment configuration
3. Separate Environments: Different tokens for dev/staging/production
4. Rotate Regularly: Change tokens every 90 days
5. Limit Scope: Use read tokens when write access isn't needed
6. Monitor Usage: Review API usage logs regularly
7. Revoke Unused Tokens: Delete old or unnecessary tokens

Webhooks and Integrations

Webhooks enable real-time notifications of content changes:

Creating Webhooks

1. Navigate to Settings > Webhooks
2. Click Add Webhook
3. Enter webhook URL (your endpoint)
4. Select events to trigger webhook:
   • Content published
   • Content updated
   • Content deleted
   • Media uploaded
5. Save webhook configuration

Webhook Security

• Use HTTPS endpoints only
• Implement signature verification
• Validate webhook payloads
• Monitor webhook logs for failures
• Rotate webhook secrets regularly

Single Sign-On (SSO)

Enterprise plans support SSO integration:

Supported SSO Providers

• SAML 2.0
• OAuth 2.0
• Okta
• Azure Active Directory
• Google Workspace
• Custom identity providers

Configuring SSO

1. Contact ButterCMS support to enable SSO
2. Provide identity provider metadata
3. Configure SAML or OAuth settings
4. Map user attributes (email, role, etc.)
5. Test authentication flow
6. Enable SSO enforcement for all users

SSO Benefits

• Centralized authentication management
• Automatic user provisioning
• Enforced multi-factor authentication
• Reduced password management overhead
• Improved security compliance

Workspace Management

Enterprise plans support multiple workspaces:

Creating Workspaces

Workspaces allow complete separation of:

• Content and content types
• Users and permissions
• API tokens and configuration
• Billing (optional)

Use Cases for Workspaces

• Multiple brands or websites
• Client-specific content management
• Staging vs. production environments
• Department or team separation
• Multi-tenant applications

Audit Logging

Track user activities and content changes:

Audit Log Features

Monitor:

• User login and logout events
• Content creation, updates, and deletions
• User invitations and role changes
• API token generation and revocation
• Settings modifications
• Failed authentication attempts

Accessing Audit Logs

1. Navigate to Settings > Audit Logs
2. Filter by:
   • User
   • Action type
   • Date range
   • Content type
3. Export logs for compliance reporting

Security Best Practices

Access Control

1. Implement RBAC: Use appropriate roles for each team member
2. Principle of Least Privilege: Grant minimum necessary permissions
3. Regular Access Reviews: Audit user list quarterly
4. Remove Inactive Users: Delete accounts for departed team members
5. Use Custom Roles: Create fine-grained permissions for specific needs

API Security

1. Protect Write Tokens: Never expose in client-side code
2. Use Environment Variables: Store tokens securely
3. Implement Rate Limiting: Protect against API abuse
4. Monitor API Usage: Set up alerts for unusual activity
5. Rotate Tokens: Change API tokens every 90 days

Authentication Security

1. Enable SSO: Use single sign-on for enterprise teams
2. Require Strong Passwords: Enforce password complexity
3. Multi-Factor Authentication: Enable MFA through SSO provider
4. Session Management: Configure appropriate timeout values
5. Monitor Failed Logins: Review failed authentication attempts

Common Issues and Solutions

Issue: API Token Not Working

Solution:

• Verify token hasn't been revoked
• Check token type (read vs. write)
• Ensure correct API endpoint URL
• Verify token permissions for the action
• Check for API rate limiting

Issue: User Cannot Access Content

Solution:

• Verify user role has permissions for content type
• Check if content type is assigned to user
• Ensure user invitation was accepted
• Verify account is not suspended
• Review custom permission settings

Issue: Webhook Not Triggering

Solution:

• Verify webhook URL is accessible
• Check webhook is enabled for the event
• Review webhook logs for errors
• Ensure HTTPS endpoint (HTTP not supported)
• Verify no firewall blocking requests

Issue: SSO Login Failures

Solution:

• Verify SAML/OAuth configuration
• Check identity provider metadata
• Ensure user email matches between systems
• Review attribute mappings
• Contact ButterCMS support for assistance

Issue: Cannot Invite More Users

Solution:

• Check your plan's user limit
• Upgrade to higher-tier plan if needed
• Remove inactive users to free slots
• Contact support for enterprise custom limits

Content Workflow and Collaboration

Content Approval Workflows

Implement editorial workflows:

1. Writers create content and save as draft
2. Reviewers approve or request changes
3. Editors publish approved content
4. Scheduled publication at specified times

Content Scheduling

Schedule content publication:

• Set publication date and time
• Automatic publishing at scheduled time
• Timezone-aware scheduling
• Preview scheduled content before publishing

Content Localization

Manage multi-language content:

• Create localized versions of content
• Assign translators to specific locales
• Review translated content before publishing
• Synchronize content across languages

Analytics Tool Access

Google Analytics 4

Manage GA4 access in Admin > Account/Property Access Management:

• Administrator: Full control over account settings and users
• Editor: Can modify configurations and settings
• Analyst: Can create reports and audiences, no configuration changes
• Viewer: Read-only access to reports and data

ButterCMS content delivered via APIs:

• Implement tracking in your frontend application
• Use ButterCMS webhooks to trigger analytics events
• Track content performance through your application analytics

Google Tag Manager

Manage GTM access in Admin > User Management:

• Administrator: Full control over container and users
• Publish: Can publish container changes to production
• Approve: Can approve changes but not publish
• Edit: Can edit tags and triggers but cannot approve or publish
• Read: View-only access to container configuration

Implement GTM in your frontend:

• Add GTM container code to your application
• Track ButterCMS content views and interactions
• Use custom events for headless content tracking

Meta Business Manager

Manage access in Business Settings > People:

• Admin: Full control over business settings and assets
• Employee: Limited access based on assigned assets and permissions

Best Practices

1. Use Role-Based Access: Assign roles based on job function, not individuals
2. Protect API Tokens: Never commit write tokens to version control
3. Enable SSO: Use single sign-on for enterprise teams
4. Monitor Audit Logs: Review user activities regularly for security
5. Rotate API Tokens: Change tokens every 90 days minimum
6. Document Permissions: Maintain clear documentation of who has access to what
7. Use Webhooks: Implement webhooks for real-time content synchronization
8. Separate Environments: Use different accounts/tokens for dev/staging/production
9. Regular Access Audits: Review team members and permissions quarterly
10. Implement Workflows: Use content approval workflows for quality control

Additional Resources

• ButterCMS Documentation
• API Reference
• Team Management Guide
• Security Best Practices
• ButterCMS Support