Adding & Removing Users on ButterCMS

Adding & Removing Users on ButterCMS — setup, configuration, and best practices for ButterCMS.

ButterCMS is a headless CMS with a SaaS dashboard for content management. User accounts are managed through the ButterCMS dashboard at buttercms.com and the ButterCMS Management API. Team collaboration features and user limits depend on your plan tier.

Adding Users via the Dashboard

Inviting Team Members

Log in to buttercms.com
Click your profile avatar in the top-right corner
Select Settings
Navigate to the Team tab
Click Invite Team Member
Enter their email address
Select a role:
- Admin -- Full access to all content, settings, API tokens, billing, and user management
- Developer -- Access to content, webhooks, API tokens, and schema management; no billing access
- Content Editor -- Create and edit content only; no access to settings, schema, or API tokens
Click Send Invite

The invited user receives an email with a sign-up or login link. They must create a ButterCMS account if they do not already have one.

Plan-Based User Limits

Plan	Team Members
Free Trial	1
Micro	1
Startup	3
Small Business	5
Enterprise	Custom

Exceeding your plan's user limit requires an upgrade. You cannot send invitations beyond the limit.

Adding Users via the Management API

ButterCMS provides a Management API (separate from the content delivery Read API) for programmatic workspace management:

# Invite a team member via the Management API
curl -X POST "https://api.buttercms.com/v2/team/invite/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jsmith@example.com",
    "role": "editor"
  }'

# List all team members
curl -s "https://api.buttercms.com/v2/team/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN" | python3 -m json.tool

# Get details for a specific team member
curl -s "https://api.buttercms.com/v2/team/MEMBER_ID/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN"

The Management API token is separate from your Read API token. Find it in Settings > API Tokens > Management API.

Updating a User's Role

# Change a team member's role
curl -X PATCH "https://api.buttercms.com/v2/team/MEMBER_ID/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Removing Users

Removing via the Dashboard

Go to Settings > Team
Find the team member
Click the Remove button next to their name
Confirm the removal

Removing via the Management API

# Remove a team member
curl -X DELETE "https://api.buttercms.com/v2/team/MEMBER_ID/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN"

What Happens to Their Content

When you remove a ButterCMS team member:

All content they created remains intact -- published blog posts, pages, and collections are unaffected
Content continues to be served through the Read API without interruption
The removed user's name may still appear in content metadata (author fields on blog posts)
Draft content is preserved and accessible to remaining team members
The user immediately loses dashboard access
Their ButterCMS account continues to exist but is disconnected from your workspace

Reassigning Blog Post Authors

If the removed user was a blog post author, update the author reference:

# Update blog post author via the Write API
curl -X PATCH "https://api.buttercms.com/v2/posts/POST_SLUG/" \
  -H "Authorization: Token YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "author": {
      "slug": "new-author-slug"
    }
  }'

# List all posts by a specific author
curl -s "https://api.buttercms.com/v2/posts/?author_slug=departing-author" \
  -H "Authorization: Token YOUR_READ_TOKEN" | python3 -m json.tool

Bulk User Management

Bulk Invite Script

#!/bin/bash
# bulk-invite.sh -- Invite multiple users from a CSV file
# CSV format: email,role

MGMT_TOKEN="YOUR_MANAGEMENT_TOKEN"
API_URL="https://api.buttercms.com/v2/team/invite/"

while IFS=',' read -r email role; do
  response=$(curl -s -w "%{http_code}" -X POST "$API_URL" \
    -H "Authorization: Token $MGMT_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$email\", \"role\": \"$role\"}")

  http_code="${response: -3}"
  if [ "$http_code" = "201" ]; then
    echo "OK: Invited $email as $role"
  else
    echo "FAIL: $email -- HTTP $http_code"
  fi
done < invites.csv

Audit Current Team Members

#!/usr/bin/env python3
"""audit_team.py -- Export ButterCMS team members to CSV."""

import requests
import csv
import sys

MGMT_TOKEN = "YOUR_MANAGEMENT_TOKEN"
headers = {"Authorization": f"Token {MGMT_TOKEN}"}

resp = requests.get("https://api.buttercms.com/v2/team/", headers=headers)
resp.raise_for_status()
members = resp.json().get("data", [])

writer = csv.writer(sys.stdout)
writer.writerow(["id", "email", "name", "role", "last_login"])

for m in members:
    writer.writerow([
        m.get("id"),
        m.get("email"),
        m.get("name", ""),
        m.get("role"),
        m.get("last_login", "never"),
    ])

SSO and Enterprise Authentication

ButterCMS supports SSO on Enterprise plans:

Google Workspace SSO -- Team members sign in with their Google Workspace account
SAML 2.0 -- Available on Enterprise plans for integration with Okta, Azure AD, OneLogin, etc.
Custom OAuth -- Contact ButterCMS support for custom OAuth provider integration

Enforcing SSO

On Enterprise plans, you can enforce SSO so that all team members must authenticate through your identity provider:

Go to Settings > Security
Enable Require SSO
Configure your SAML endpoint URL and X.509 certificate
Test with a non-admin user before enforcing for everyone

When SSO is enforced, the email/password login option is hidden for non-admin users. Admins retain password-based login as a fallback.

API Token Security

When managing users, also manage API token access:

# List all API tokens (Management API)
curl -s "https://api.buttercms.com/v2/tokens/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN"

# Rotate the Read API token
curl -X POST "https://api.buttercms.com/v2/tokens/rotate/read/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN"

# Rotate the Write API token
curl -X POST "https://api.buttercms.com/v2/tokens/rotate/write/" \
  -H "Authorization: Token YOUR_MANAGEMENT_TOKEN"

After removing a user who had access to API tokens, rotate all tokens as a precaution.

Offboarding Checklist

Remove the team member from Settings > Team (or via API)
Rotate API tokens -- Read, Write, and Management tokens should all be regenerated
Reassign blog authors -- Update author references on posts attributed to the departing user
Review webhooks -- If the user configured webhooks pointing to external services, verify they are still needed
Check integrations -- Remove any connected services (GitHub, Netlify, Vercel) that used the departing user's personal credentials
Update SSO provider -- If using SAML/Google SSO, deactivate the user in your identity provider
Audit content -- Review recent changes to ensure no unauthorized modifications were made before departure

Nach oben