TinyMCE AI JWT Permissions

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.

For information about JWT authentication setup and required claims, see JWT Authentication.

Quick Reference

Category Permissions

Admin

ai:admin

Models

ai:models:*, ai:models:<provider>:*, ai:models:<provider>:<model-name>, ai:models:agent

Conversations

ai:conversations:*, ai:conversations:read, ai:conversations:write, ai:conversations:websearch, ai:conversations:reasoning

Context

ai:conversations:context:*, ai:conversations:context:files:*, ai:conversations:context:files:<format>, ai:conversations:context:urls

Actions

ai:actions:*, ai:actions:custom, ai:actions:system:*, ai:actions:system:<action-name>

Reviews

ai:reviews:*, ai:reviews:custom, ai:reviews:system:*, ai:reviews:system:<review-name>

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

Permission Description

ai:admin

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

Model Permissions

Permission Description

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 (for example, ai:models:openai:*, ai:models:anthropic:*).

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

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

ai:models:agent ⭐ Recommended

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

Permission Description

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

Permission Description

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 (for example, ai:conversations:context:files:pdf, ai:conversations:context:files:docx).

ai:conversations:context:urls

Ability to use web URLs as context sources.

Actions Permissions

Permission Description

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

Permission Description

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.