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 |
|
Models |
|
Conversations |
|
Context |
|
Actions |
|
Reviews |
|
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 are an array of strings in the auth.ai.permissions claim of the JWT. Each string has the form ai:<permission-type>:<permission-value>, where <permission-type> is one of models, conversations, actions, reviews, or admin. The <permission-value> can contain the * wildcard. The service ignores any string that does not match this format.
Admin permissions
| Permission | Description |
|---|---|
|
Grants full access to all TinyMCE AI features, models, and capabilities. Use with caution in production environments. |
Model permissions
| Permission | Description |
|---|---|
|
Access to all available AI models. Use with caution as this includes access to new models that may be more expensive. |
|
Access to all models from a specific provider (for example, |
|
Access to a specific model (for example, |
|
Access to the agent model which automatically selects the best model for each request. This is the recommended permission for most use cases. |
Conversation messages, custom actions, and custom reviews also require the permission for the model that the request uses. System actions and system reviews require only their own permission.
Conversation permissions
| Permission | Description |
|---|---|
|
Full access to all conversation features including read, write, web search, and reasoning. |
|
Ability to read and list conversations, messages, and attachments. |
|
Ability to create, update, and delete conversations, and to send messages. Requires |
|
Ability to use web search capability in conversations. |
|
Ability to use reasoning capability in conversations. |
Context permissions
| Permission | Description |
|---|---|
|
Access to all context types (files and URLs). |
|
Access to all file types for context. |
|
Access to specific file formats (for example, |
|
Ability to use web URLs as context sources. |
Uploading a file also requires ai:conversations:write.
Actions permissions
| Permission | Description |
|---|---|
|
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: |
Quick Actions that open in Chat, such as Explain, Summarize, and Highlight key points, and custom Quick Actions with type: 'chat', send a conversation message. They require the conversation permissions and the permission for the selected model.
Reviews permissions
| Permission | Description |
|---|---|
|
Access to all review types, including custom and system reviews. |
|
Ability to run custom reviews with free-form prompts, including integrator-defined reviews. |
|
Access to all pre-defined system reviews. |
|
Access to specific system reviews. Examples: |
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"
]
}
}
}All tinymceai plugin features
This set covers Chat with web search, reasoning, and attachments, plus system and custom Quick Actions and reviews, with the Agent model. If a custom Quick Action or custom review uses a specific model, add the permission for that model.
{
"auth": {
"ai": {
"permissions": [
"ai:conversations:read",
"ai:conversations:write",
"ai:conversations:websearch",
"ai:conversations:reasoning",
"ai:conversations:context:*",
"ai:models:agent",
"ai:actions:*",
"ai:reviews:*"
]
}
}
}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 code missing-permissions. The data.missingPermissions array lists the permissions that the token lacks. For the response body, see Error responses. Common issues include missing model permissions, file type restrictions, feature access without permission, and action/review access without permission.
Related features
-
JWT Authentication: JWT authentication setup and required claims.
-
AI Models: Model selection and capabilities.
-
Chat: Interactive AI discussions.
-
Review: Content improvement.
-
Quick Actions: Content transformation.