Permissions

You can control access to AI features, models, and capabilities based on user roles, subscription tiers, and organizational requirements.

The CKEditor AI permission system allows integrators to manage their users’ access to specific functionality. This enables control over AI features, models, and capabilities based on user roles, subscription tiers, or organizational requirements. Permissions provide flexible access control, role-based management, security, and cost control for premium models and capabilities.

For SaaS applications, users in different tiers might have access to different features. You can upgrade/downgrade users between tiers while preserving their data, control file type access where higher tiers can use more file types, manage model access where premium tiers can use more powerful models, and implement feature restrictions where basic tiers have limited functionality.

For enterprise systems with multiple roles, you can implement file upload restrictions to prevent certain roles from uploading confidential information, provide review-only access for some users, disable manual model selection for users unfamiliar with AI differences, and grant feature-specific access for editors, reviewers, and administrators.

Permissions are specified in the JWT token’s auth.ai.permissions claim as an array of permission strings. Each permission follows the format: ai:<permission-type>:<permission-value>

Grants full administrative access to the AI.

Model permissions control which AI models users can access across all features.

Wildcard permission grant access to all available models. This is the default setting for most users, but new, potentially expensive models become automatically available.

Access to all models from a specific provider. Examples: ai:models:openai:*, ai:models:anthropic:*, ai:models:google:*

Access to a specific model from a provider. Examples: ai:models:openai:gpt-5, ai:models:anthropic:claude-4-sonnet

Allow users to use the agent-1 model for optimal performance. No need to manually select models; automatic optimization for performance and cost.

Wildcard permission for all conversation-related features, including all conversation permissions below.

Access to chat interface and conversation history, including loading conversation lists, viewing messages, and accessing chat UI.

Ability to create and modify conversations, including sending messages and creating/updating/deleting conversations. Requires both read and write permissions for full functionality.

Enable web search capability in conversations.

Enable reasoning capability in conversations.

Context permissions control which types of content can be attached to conversations.

Access to all context sources, including all file types, web resources, and other context types.

Access to all supported file types, including PDF, DOCX, TXT, MD, PNG, JPEG, HTML.

Access to specific file formats. Examples:

• ai:conversations:context:files:pdf
• ai:conversations:context:files:docx
• ai:conversations:context:files:png
• ai:conversations:context:files:jpg

Ability to add web URLs as context.

Access to all action types, including custom and system actions.

Ability to run custom actions with free-form prompts.

Access to all pre-defined system actions.

Access to specific system actions. Examples:

• ai:actions:system:improve-writing
• ai:actions:system:fix-grammar
• ai:actions:system:translate

Access to all review types, including custom and system reviews.

Ability to run custom reviews with free-form prompts.

Access to all pre-defined system reviews.

Access to specific system reviews. Examples:

• ai:reviews:system:correctness
• ai:reviews:system:clarity
• ai:reviews:system:make-tone-professional

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:read",
        "ai:conversations:write",
        "ai:models:agent",
        "ai:conversations:context:files:pdf",
        "ai:conversations:context:files:docx"
      ]
    }
  }
}

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:conversations:*",
        "ai:models:*",
        "ai:actions:system:*",
        "ai:reviews:system:*"
      ]
    }
  }
}

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:admin"
      ]
    }
  }
}

{
  "auth": {
    "ai": {
      "permissions": [
        "ai:reviews:system:correctness",
        "ai:reviews:system:clarity",
        "ai:models:gpt-4.1-mini"
      ]
    }
  }
}

Begin with minimal, specific permissions based on actual requirements. Use wildcards only for testing environments and power users who need comprehensive access. Gradually expand permissions based on user needs and usage patterns.

Avoid ai:models:* in production to prevent unexpected access to new expensive models. Use provider-specific permissions like ai:models:openai:* for better control, or specify exact models for maximum control. Start with common formats (PDF, DOCX, TXT, PNG, JPEG) and add specialized formats only when needed.

When a user lacks required permissions, the API returns a 403 Forbidden error with the message “No permissions to the resource”. Common issues include missing model permissions, file type restrictions, feature access without permission, and action/review access without permission.

• Learn about AI Models for model selection and capabilities.
• Learn about Conversations for interactive AI discussions.
• Explore Reviews for content improvement.
• Discover Actions for content transformation.
• API Documentation – Complete API reference for CKEditor AI.