Sanity Roles and Permissions

Sanity provides a role-based access control system for managing project members who create content, manage datasets, and administer projects. Understanding the permission levels is critical for secure, efficient Sanity project management.

Sanity Role Hierarchy

Sanity has four primary project roles with decreasing levels of access:

1. Administrator - Full project control, billing access, member management
2. Editor - Full content management across all datasets
3. Contributor - Limited content editing (can read and write)
4. Custom Roles - Project-specific roles with granular permissions

Note: Unlike traditional CMSes, Sanity is API-first. Roles primarily control API access and Sanity Studio permissions.

Detailed Role Permissions

Administrator (Highest Privilege)

Administrators have unrestricted access to all project features and are the only role with billing and project deletion capabilities.

Core Permissions:

• All Editor permissions (below)
• Manage project members (invite, remove, change roles)
• Access billing and subscription management
• Delete datasets
• Manage API tokens with any permission level
• Configure project settings
• Set up webhooks and CORS origins
• Manage deployment configurations
• Access project analytics and usage data

Access to:

• All datasets (production, staging, development, etc.)
• Sanity Studio (full access)
• Sanity Manage (project settings)
• Content Lake API (read/write)
• Management API (full access)
• Billing dashboard

Cannot:

• Delete the entire project (requires organization owner)

Best Practices:

• Reserve Administrator for tech leads or project owners
• Limit to 2-3 trusted administrators
• Document Administrator credentials securely
• Enable 2FA on accounts with access
• Review Administrator actions monthly

When to Use Administrator:

• Initial project setup and configuration
• Managing team members and roles
• Billing and plan management
• Infrastructure changes (webhooks, CORS, API tokens)
• Dataset creation/deletion

Editor

Editors can manage all content but lack project administration capabilities.

Core Permissions:

• Create, read, update, and delete documents in all datasets
• Upload and manage assets
• Access Sanity Studio
• Query content via GROQ/GraphQL
• Publish and unpublish documents
• Create drafts
• Use Content Lake API

Access to:

• All datasets (based on configuration)
• Sanity Studio (full content access)
• Content Lake API (read/write)
• Asset management

Cannot:

• Invite or remove project members
• Change user roles
• Access billing or usage data
• Create or manage API tokens
• Configure webhooks or project settings
• Delete datasets
• Manage CORS origins

Best Practices:

• Assign to content managers and developers
• Ideal for day-to-day content operations
• Monitor Editor actions via activity logs
• Grant Editor for content quality control

When to Use Editor:

• Content creation and management
• Developing against Sanity (local/staging)
• Managing editorial calendar
• Asset organization and optimization

Editor Workflow Example:

1. Create draft document in Sanity Studio
2. Edit content and add assets
3. Preview changes
4. Publish document
5. Query published content via API

Contributor

Contributors can read and write content but have more limited access than Editors.

Core Permissions:

• Read documents in assigned datasets
• Create and edit own documents
• Upload assets
• Access Sanity Studio (limited)
• Query content via GROQ/GraphQL (read-only in some configs)

Access to:

• Assigned datasets only
• Sanity Studio (content editing)
• Content Lake API (read/write, limited)

Cannot:

• Delete documents (in default config)
• Access all datasets
• Manage assets uploaded by others
• Invite users or manage members
• Access project settings
• Create API tokens

Limitations:

• May not publish documents (project-dependent)
• Limited dataset access
• Cannot manage project-wide assets
• No access to project settings

Best Practices:

• Assign to guest contributors or freelance writers
• Use for users who need content access but not full control
• Review Contributor actions regularly
• Transition to Editor after trust established

When to Use Contributor:

• Guest bloggers
• Freelance content creators
• Junior team members
• Limited access scenarios

Contributor Workflow:

1. Access Sanity Studio
2. Create/edit documents in assigned datasets
3. Save changes (may require Editor to publish)
4. No access to sensitive project settings

Custom Roles

Sanity allows creating custom roles with granular permissions.

Capabilities:

• Define specific read/write permissions per dataset
• Control access to specific document types
• Set field-level permissions
• Create role-based workflows

Example Custom Roles:

• Viewer - Read-only access to content
• Asset Manager - Manage assets but not documents
• Developer - Full API access, limited Studio access
• Reviewer - Read documents, add comments, no edits

Creating Custom Roles:

Custom roles are defined in your Sanity Studio sanity.config.ts:

import { defineConfig } from 'sanity'

export default defineConfig({
  // ... other config
  projectId: 'your-project-id',
  dataset: 'production',

  plugins: [
    // Custom role plugin
  ],

  // Note: Advanced role configuration requires Enterprise plan
  // or custom implementation via document-level permissions
})

Field-Level Permissions Example:

// schema/post.ts
export default {
  name: 'post',
  type: 'document',
  fields: [
    {
      name: 'title',
      type: 'string',
      // All roles can read
      readOnly: ({ currentUser }) => {
        return !['administrator', 'editor'].includes(currentUser.role)
      }
    },
    {
      name: 'publishedAt',
      type: 'datetime',
      // Only administrators can edit
      readOnly: ({ currentUser }) => {
        return currentUser.role !== 'administrator'
      }
    }
  ]
}

Permission Matrix

Role Selection Guidelines

Choose Administrator When:

• Managing project infrastructure
• Handling billing and subscriptions
• Managing team members and roles
• Configuring webhooks and integrations
• Setting up API tokens for services
• Full accountability for project operations

Choose Editor When:

• Day-to-day content management
• Developing frontend applications
• Managing content workflows
• Not requiring project administration
• Need full content access across datasets

Choose Contributor When:

• Limited content editing needs
• Guest contributors or freelancers
• Junior team members learning platform
• Need content access without full control

Choose Custom Role When:

• Specific workflow requirements
• Need granular permission control
• Read-only access needed
• Field-level permission requirements

Dataset-Level Permissions

Sanity allows configuring role access per dataset:

Production Dataset:

• Administrators: Full access
• Editors: Read/write (with caution)
• Contributors: Read-only or no access
• Viewers: Read-only

Staging Dataset:

• Administrators: Full access
• Editors: Full access
• Contributors: Read/write
• Developers: Full access

Development Dataset:

• All roles: Full access for testing

Configuring Dataset Access:

1. Navigate to Sanity Manage → Project → Project members
2. Click on user
3. Under Dataset access, select which datasets
4. Save changes

API Token Permissions

API tokens can have different permission levels:

Token Types:

• Read token - Query content only
• Write token - Create/update documents
• Deploy Studio token - Deploy Sanity Studio
• Admin token - Full API access (Management API)

Creating API Tokens:

1. Sanity Manage → Project → API → Tokens
2. Click Add token
3. Set:
   • Token name
   • Permissions (Read, Write, Admin)
   • Dataset access
4. Copy token (shown only once)
5. Store securely

Token Best Practices:

• Use read-only tokens for frontend
• Limit token scope to specific datasets
• Rotate tokens regularly
• Never commit tokens to Git
• Use environment variables

Security Best Practices

Role-Based Security

1. Principle of Least Privilege

   • Grant minimum role needed for job function
   • Regularly review and adjust roles
   • Remove unused accounts quarterly

2. Access Audits

   • Monthly review of all project members
   • Verify roles match current responsibilities
   • Document role changes with justification

3. API Token Security

   • Rotate tokens every 90 days
   • Use read-only tokens when possible
   • Audit token usage in project analytics
   • Revoke unused tokens immediately

4. Activity Monitoring

   • Review activity logs in Sanity Manage
   • Monitor for anomalous behavior
   • Investigate suspicious document deletions
   • Track schema changes

Sanity Cloud Security

Built-in Security:

• SOC 2 Type II certified
• GDPR compliant
• Encrypted data at rest and in transit
• Role-based access control (RBAC)
• Activity logging

Your Responsibility:

• Manage user accounts securely
• Protect API tokens
• Configure appropriate roles
• Regular access audits
• Monitor activity logs

Common Role Scenarios

Scenario 1: Small Development Team (2-3 people)

• 1 Administrator - Tech lead or project owner
• 2 Editors - Developers with full content access

Scenario 2: Content Team (5-10 people)

• 1 Administrator - CTO or technical owner
• 1-2 Editors - Senior developers/content managers
• 3-5 Contributors - Content creators and writers

Scenario 3: Large Organization (10+ people)

• 2 Administrators - CTO, DevOps lead
• 3-5 Editors - Developers, content managers
• 5+ Contributors - Content team, freelancers
• Custom Viewers - Stakeholders, reviewers

Scenario 4: Agency Managing Client Projects

• 1 Administrator (Agency) - Project management
• 1 Editor (Client) - Content management
• Contributors (Freelancers) - Content creation
• Viewers (Stakeholders) - Review-only access

Next Steps

• Adding and Removing Users - Manage project members
• User Management Overview - User governance and access control
• Sanity Integrations - Configure tracking and tools

Related Resources

• Sanity Access Control
• Sanity Management API
• Sanity Security
• Sanity Enterprise Features