Contentful Roles and Permissions | OpsBlu Docs

Contentful Roles and Permissions

Complete guide to understanding and managing roles and permissions in Contentful

Comprehensive guide to Contentful's role-based access control system, covering organization roles, space roles, custom roles, and permission management.

Understanding Contentful's Permission Model

Two-Level Permission System

Contentful uses a dual-layer permission structure:

Organization Level:

  • Controls billing and subscription access
  • Manages team members
  • Creates and manages spaces
  • Organization-wide permissions

Space Level:

  • Controls content and asset access
  • Content model management
  • Publishing permissions
  • API key management
Organization (Company)
├── Organization Role (Admin/Developer/Member)
└── Spaces
    ├── Space 1 → Space Role (Developer/Editor/Author)
    ├── Space 2 → Space Role (Developer/Editor/Author)
    └── Space 3 → Space Role (Developer/Editor/Author)

Permission Inheritance

How it works:

  • Organization role does NOT automatically grant space access
  • Users must be added to each space separately
  • Space roles are independent per space
  • A user can have different roles in different spaces

Organization Roles

Organization Admin

Full organizational control:

Permissions:

  • ✓ Manage billing and subscription
  • ✓ Invite/remove organization members
  • ✓ Change organization settings
  • ✓ Create/delete spaces
  • ✓ View all spaces
  • ✓ Manage organization roles
  • ✓ Access usage analytics
  • ✓ Configure SSO (Enterprise)
  • ✓ Manage API tokens

Use cases:

  • Company owner
  • IT administrator
  • Operations manager

Security considerations:

  • Can modify billing (financial impact)
  • Can remove other admins
  • Can delete spaces (data loss risk)
  • Limit to 2-3 trusted individuals

Organization Developer

Technical access without billing:

Permissions:

  • ✓ View organization settings
  • ✓ Create spaces
  • ✓ Access all spaces (view only by default)
  • ✓ Manage personal API tokens
  • ✓ View usage analytics
  • ✗ Manage billing
  • ✗ Invite/remove members
  • ✗ Change organization settings
  • ✗ Configure SSO

Use cases:

  • Lead developers
  • DevOps engineers
  • Technical architects

Best for: Technical staff who need to create spaces and manage development environments.

Organization Member

Minimal organization access:

Permissions:

  • ✓ View organization name
  • ✓ Access assigned spaces only
  • ✓ Manage personal profile
  • ✗ View organization settings
  • ✗ Create spaces
  • ✗ View other spaces
  • ✗ Invite members

Use cases:

  • Content editors
  • Marketing team
  • External contractors
  • Support staff

Best practice: Default role for most team members.

Space Roles

Built-in Space Roles

Contentful provides four default space roles:

Developer (Space Admin)

Full space control:

Permissions:

  • ✓ Create/edit/delete content types
  • ✓ Create/edit/delete/publish entries
  • ✓ Create/edit/delete assets
  • ✓ Manage space settings
  • ✓ Create/delete API keys
  • ✓ Manage webhooks
  • ✓ Configure locales
  • ✓ Manage space members
  • ✓ Delete space (if org admin)
  • ✓ Access all content statuses

Use cases:

  • Technical leads
  • Senior developers
  • Space administrators

Warning: Full access to destructive operations.

Content Editor

Full content management:

Permissions:

  • ✓ Create/edit/delete/publish entries
  • ✓ Create/edit/delete assets
  • ✓ Edit all content statuses
  • ✓ Bulk operations
  • ✗ Modify content types
  • ✗ Manage space settings
  • ✗ Create API keys
  • ✗ Manage webhooks
  • ✗ Add/remove space members

Use cases:

  • Senior content managers
  • Editorial leads
  • Content strategists

Best for: Staff who manage content but shouldn't modify structure.

Content Author

Create and edit own content:

Permissions:

  • ✓ Create entries
  • ✓ Edit own entries
  • ✓ Delete own entries
  • ✓ Change status of own entries
  • ✓ Create/edit/delete assets
  • ✗ Edit others' entries
  • ✗ Publish to production (depends on workflow)
  • ✗ Modify content types
  • ✗ Manage settings

Use cases:

  • Content writers
  • Marketing team members
  • Junior editors
  • Freelance contributors

Best for: Team members who create content but need editorial review.

Translator

Translation-focused access:

Permissions:

  • ✓ View all entries
  • ✓ Edit localized fields only
  • ✓ View assets
  • ✗ Edit non-localized fields
  • ✗ Create/delete entries
  • ✗ Create/delete assets
  • ✗ Modify content types

Use cases:

  • Translation agencies
  • Localization teams
  • International content managers

Best for: Translation workflows without allowing structural changes.

Custom Space Roles

Create custom roles for specific needs:

Access Custom Roles

Space Settings → Roles → Create role

Available on:

  • Team plan (limited)
  • Business plan (more flexibility)
  • Enterprise plan (unlimited)

Creating Custom Role

Step 1: Define Role Basics

Name: Content Reviewer
Description: Can review and approve content for publication

Step 2: Configure Permissions

Content Model:

  • View content types
  • Create content types
  • Edit content types
  • Delete content types

Entries:

  • View entries
  • Create entries
  • Edit own entries
  • Edit all entries
  • Delete own entries
  • Delete all entries
  • Change entry status

Assets:

  • View assets
  • Create assets
  • Edit assets
  • Delete assets

Settings:

  • Manage space settings
  • Manage API keys
  • Manage webhooks
  • Manage members

Step 3: Entry Status Permissions

Define which statuses role can:

  • View: Draft, In Review, Approved, Published
  • Change from: Draft → In Review
  • Change to: In Review, Rejected

Example: Content Reviewer Role

Use case: Review content and approve for publication

Permissions:

Entries:
✓ View all entries
✓ Edit all entries (for corrections)
✓ Change status: Draft → In Review
✓ Change status: In Review → Approved
✓ Change status: In Review → Rejected

Assets:
✓ View assets
✗ Create/edit/delete assets

Content Model:
✓ View content types (read-only)
✗ Edit content types

Settings:
✗ All settings disabled

Example: SEO Specialist Role

Use case: Manage SEO fields across all content

Permissions:

Entries:
✓ View all entries
✓ Edit all entries
✗ Delete entries
✗ Change entry status (no publish)

Specific fields:
✓ Edit: SEO Title, Meta Description, URL Slug, OG Image
✗ Edit: Other content fields

Assets:
✓ View assets
✓ Create assets (for OG images)

Content Model:
✓ View content types
✗ Edit content types

Implementation:

  • Requires field-level permissions (Enterprise)
  • Use workflows to restrict non-SEO changes

Permission Patterns by Use Case

Small Team (3-5 people)

Structure:

Organization:
├── Owner (Org Admin) - 1 person
└── Team Members (Org Members) - 4 people

Space Permissions:
├── Owner: Developer role
├── Lead Editor: Content Editor role
├── Writers (2): Content Author role
└── Designer: Custom role (assets only)

Medium Team (10-20 people)

Structure:

Organization:
├── Org Admin - 2 people (owner + ops)
├── Org Developer - 2 people (tech leads)
└── Org Members - 16 people

Production Space:
├── Developers (2): Developer role
├── Content Managers (3): Content Editor role
├── Content Writers (8): Content Author role
├── Translators (2): Translator role
└── Reviewers (3): Custom "Content Reviewer" role

Staging Space:
├── Developers (2): Developer role
├── Content Managers (3): Content Editor role
└── QA Team (2): Custom "QA Tester" role

Enterprise (50+ people)

Structure:

Organization:
├── Org Admin - 3 people
├── Org Developer - 5 people
└── Org Members - 50+ people

Multiple Spaces by Region/Brand:
├── Space: US Website
│   ├── Regional Manager: Developer
│   ├── Content Team: Editors/Authors
│   └── Local Translators: Translator
├── Space: EU Website
│   └── (Similar structure)
└── Space: Shared Assets
    └── Brand Team: Asset-only custom role

Additional controls:

  • SSO integration
  • Custom workflows per space
  • API rate limiting per role
  • Audit logging

Workflow and Status Permissions

Entry Statuses

Default statuses:

  • Draft
  • Changed
  • Published
  • Archived

Custom statuses (Enterprise):

  • In Review
  • Approved
  • Scheduled
  • Rejected

Status-Based Permissions

Configure per role:

Content Author:
├── Can view: All statuses
├── Can create: Draft
├── Can change from Draft to: In Review
├── Cannot: Publish, Archive
└── Cannot: Change others' entries

Content Reviewer:
├── Can view: All statuses
├── Can change from In Review to: Approved, Rejected
├── Cannot: Create entries
└── Cannot: Publish

Content Editor:
├── Can view: All statuses
├── Can change to any status
├── Can publish
└── Can archive

Workflow Example: Editorial Process

Step 1: Draft → In Review

  • Created by: Content Author
  • Action: Submit for review

Step 2: In Review → Approved/Rejected

  • Reviewed by: Content Reviewer
  • Actions: Approve or request changes

Step 3: Approved → Published

  • Published by: Content Editor or Developer
  • Action: Publish to production

Step 4: Published → Archived

  • Archived by: Content Editor
  • Action: Remove outdated content

Field-Level Permissions (Enterprise)

Field Permission Control

Enable per field:

Content Type → Field → Appearance → Field permissions

Options:

  • All roles: Everyone can view and edit
  • Specific roles: Select which roles can view/edit
  • Read-only for some: Some can view, others can edit
  • Hidden: Completely hidden from specific roles

Use Cases

Internal Notes Field:

Visible to: Content Editors, Developers
Hidden from: Content Authors, Translators
Use: Editorial notes not for writers

SEO Fields:

Editable by: SEO Specialists, Content Editors, Developers
Read-only for: Content Authors (can see, not edit)
Use: Maintain SEO consistency

Pricing Information:

Editable by: E-commerce Managers, Developers
Hidden from: Content Authors, Translators
Use: Protect sensitive business data

API Keys and Permissions

Content Delivery API (CDA)

Public API keys:

  • Read-only access to published content
  • Safe for frontend applications
  • No permission management needed

Who can create:

  • Organization Admin
  • Organization Developer
  • Space Developer role

Content Management API (CMA)

Personal access tokens:

User Settings → API keys → Generate personal access token

Permissions:

  • Inherits user's organization and space roles
  • Same access as user has in web interface
  • Can be scoped to specific spaces

Management tokens (Service accounts):

Space Settings → API keys → Content management tokens

Permissions:

  • Can have custom permissions
  • Independent of user roles
  • Used for automated workflows
  • Can be scoped narrowly

Security best practices:

  • Use management tokens for automation
  • Limit personal tokens to development
  • Rotate tokens regularly
  • Never commit tokens to code repositories
  • Use environment variables

Best Practices

Organization Level

Minimize Org Admins:

  • ✓ 2-3 org admins maximum
  • ✓ Always have backup admin
  • ✗ Don't make everyone admin

Use Org Member by Default:

  • ✓ Default new users to Member
  • ✓ Grant space access as needed
  • ✓ Prevents unauthorized space access

Regular Audits:

  • Review org members quarterly
  • Remove inactive accounts
  • Verify admin privileges

Space Level

Principle of Least Privilege:

  • Start with minimum role needed
  • Grant Author instead of Editor when possible
  • Use custom roles for specific needs

Separate Environments:

Development Space: Developers only
Staging Space: Developers + Content Team
Production Space: Restricted publishing

Content Workflow:

  • Require review before publish
  • Use status-based permissions
  • Separate write and publish permissions

Security

Two-Factor Authentication:

  • Required for Org Admins
  • Recommended for Developers
  • Available to all users

SSO Integration (Enterprise):

  • Centralized authentication
  • Automatic provisioning
  • Role mapping from identity provider

API Token Management:

  • Use management tokens for automation
  • Scope tokens to minimum access
  • Rotate tokens quarterly
  • Revoke tokens when users leave

Troubleshooting

User Can't Access Space

Diagnosis:

  1. Check organization membership
  2. Verify space membership
  3. Confirm space role assignment

Solution:

Space Settings → Members → Add member → Select user → Assign role

User Can't Publish Content

Possible causes:

  • Content Author role (can't publish)
  • Custom role without publish permission
  • Entry status restrictions

Solution:

  • Upgrade to Content Editor role
  • Or create custom role with publish permission
  • Or adjust workflow permissions

API Token Not Working

Check:

  • Token not revoked
  • Token has space access
  • Token permissions match requirements
  • Using correct API endpoint (CDA vs CMA)

Fix:

Space Settings → API keys → Verify token status → Regenerate if needed

Can't Modify Content Type

Cause: Only Developer role can edit content types

Solutions:

  • Request Developer role
  • Ask Developer to make changes
  • Use Content Editor for entry changes only

Next Steps

Back to top