---
title: "TinyMCE AI JWT Permissions"
description: "JWT permissions system for TinyMCE AI"
canonical_url: "https://www.tiny.cloud/docs/tinymce/latest/tinymceai-permissions/"
md_url: "https://www.tiny.cloud/docs/tinymce/latest/tinymceai-permissions/index.md"
version: "latest"
last_updated: "2026-09-28T00:27:52Z"
tokens: 1621
---
# 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](../tinymceai-jwt-authentication-intro/).

## 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

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

### Premium User

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

### Enterprise Admin

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

### Restricted User (Review Only)

```json
{
  "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.

## Related Features

- [JWT Authentication](../tinymceai-jwt-authentication-intro/): JWT authentication setup and required claims.
- [AI Models](../tinymceai-models/): Model selection and capabilities.
- [Chat](../tinymceai-chat/): Interactive AI discussions.
- [Review](../tinymceai-review/): Content improvement.
- [Quick Actions](../tinymceai-actions/): Content transformation.