TinyMCE AI Permissions

Overview

TinyMCE AI uses a permission-based access control system to manage user access to AI features. Permissions are specified in JWT tokens and control which features, models, and capabilities users can access.

Use Cases

  • Role-based access – Different user roles have different AI capabilities

  • Cost control – Limit access to expensive models or features

  • Feature gating – Enable specific AI features for premium users

  • Security – Restrict access to sensitive AI operations

Permission Format

Permissions follow a hierarchical format: ai:<category>:<subcategory>:<specific-permission>

Admin Permissions

ai:admin

Grants full access to all TinyMCE AI features, models, and capabilities. Use with caution in production environments.

Model Permissions

ai:models:*

Access to all available AI models. Use with caution as this includes access to new models that may be more expensive.

ai:models:<provider>:*

Access to all models from a specific provider (e.g., ai:models:openai:*, ai:models:anthropic:*).

ai:models:<provider>:<model-name>

Access to a specific model (e.g., ai:models:openai:gpt-4o, ai:models:anthropic:claude-3-sonnet).

Access to the agent model which automatically selects the best model for each request. This is the recommended permission for most use cases.

Conversation Permissions

ai:conversations:*

Full access to all conversation features including read, write, web search, and reasoning.

ai:conversations:read

Ability to read and list conversations.

ai:conversations:write

Ability to create and send messages in conversations.

ai:conversations:websearch

Ability to use web search capability in conversations.

ai:conversations:reasoning

Ability to use reasoning capability in conversations.

Context Permissions

ai:conversations:context:*

Access to all context types (files and URLs).

ai:conversations:context:files:*

Access to all file types for context.

ai:conversations:context:files:<format>

Access to specific file formats (e.g., ai:conversations:context:files:pdf, ai:conversations:context:files:docx).

ai:conversations:context:urls

Ability to use web URLs as context sources.

Actions Permissions

ai:actions:*

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

ai:actions:custom

Ability to run custom actions with free-form prompts.

ai:actions:system:*

Access to all pre-defined system actions.

ai:actions:system:<action-name>

Access to specific system actions. Examples:

  • ai:actions:system:improve-writing

  • ai:actions:system:fix-grammar

  • ai:actions:system:translate

Reviews Permissions

ai:reviews:*

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

ai:reviews:custom

Ability to run custom reviews with free-form prompts.

ai:reviews:system:*

Access to all pre-defined system reviews.

ai:reviews:system:<review-name>

Access to specific system reviews. Examples:

  • ai:reviews:system:correctness

  • ai:reviews:system:clarity

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

Permission Examples

Basic User

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

Premium User

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

Enterprise Admin

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

Restricted User (Review Only)

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

Best Practices

Permission Design

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.

Error Handling

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.

Next Steps