Permissions

Permissions decide which models, file formats, actions, and reviews a user can use with CKEditor AI. You put them in the auth.ai.permissions claim of the JWT you issue to that user.

This page lists every scope, the wildcard rules, and the 403 error a missing scope produces. To build the token endpoint, see Authentication.

Permissions are an array of strings in the token’s auth.ai.permissions claim. Each string has the form ai:<type>:<value>.

A trailing * matches every segment below it, at any depth. ai:models:* grants every model from every provider. A * inside a segment is a wildcard for that segment only. ai:models:openai:gpt-4* grants every OpenAI model with an id that starts with gpt-4.

Permissions decide which features a token may use. They do not grant access to a single conversation or document.

• Conversations: a user sees only the conversations they created. The sub of the token decides which ones.
• Document Processing: any token with ai:documents:process can send any document. Your backend decides who sends what.

Three tokens, from the narrowest to the widest. For the profiles most integrations start from, see Set the user permissions.

A chat user on the Agent model who can attach PDF and DOCX files, and nothing else: no actions, no reviews, no images, and no URLs.

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

A token that runs two system reviews and nothing else. A system review checks only its own scope, so the token needs no model scope.

{
  "auth": {
	"ai": {
	  "permissions": [
		"ai:reviews:system:correctness",
		"ai:reviews:system:clarity"
	  ]
	}
  }
}

A backend token for managing contexts and MCP servers and reading usage. It satisfies every check, so never issue it to a browser or an end user.

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

Satisfies every permission check in the API.

Never issue an admin token to a browser or an end user. Call the admin endpoints from your backend only, and grant every other user the scopes in the sections below.

ai:admin is required for these operations:

• management of the context library: contexts, prompts, and files,
• management of MCP server definitions,
• access to other users’ conversations: list, read, and delete,
• access to billing usage.

Model permissions decide which models a user can use, in every feature.

Access to every model, including models added later.

Access to every model from one provider. Examples: ai:models:openai:*, ai:models:anthropic:*, ai:models:google:*.

Access to one model. Examples: ai:models:openai:gpt-5, ai:models:anthropic:claude-sonnet-5. See Models for the model ids.

Access to the Agent model. The Agent model selects a model for each request.

Access to every scope in this section and in “Conversation context permissions”.

Access to conversation history: the list of conversations and their messages.

Lets the user send messages, and create, update, and delete conversations. These operations also check ai:conversations:read, so grant both.

Access to web search in conversations and document processing calls.

Access to reasoning in conversations and document processing calls.

Conversation context permissions decide which content a user can attach to a conversation.

Access to every context source: all file formats and web URLs.

Access to every supported file format. The formats are listed below.

Access to one file format. One permission per format:

• ai:conversations:context:files:pdf
• ai:conversations:context:files:docx
• ai:conversations:context:files:png
• ai:conversations:context:files:jpeg
• ai:conversations:context:files:txt
• ai:conversations:context:files:md
• ai:conversations:context:files:html

Lets the user add web URLs as context.

Access to every scope in this section.

Lets the user run document processing calls.

Access to custom and system actions.

Lets the user run custom actions with free-form prompts. The request also needs the scope of the model that the request names.

Access to every system action.

Access to one system action. Examples:

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

Access to custom and system reviews.

Lets the user run custom reviews with free-form prompts. The request also needs the scope of the model that the request names.

Access to every system review.

Access to one system review. Examples:

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

Context library permissions decide which contexts in the context library a user can use. Each permission names a context by its ID. The check runs wherever a request references a context: in conversations, in system actions, and in system reviews.

Access to every context in the library.

Access to one context by its exact ID. Examples:

• ai:contexts:product-docs
• ai:contexts:legal-guidelines

Access to every context with an ID that matches a wildcard pattern. Examples:

• ai:contexts:team-* matches every context whose ID starts with team-.
• ai:contexts:*-draft matches every context whose ID ends with -draft.

Start with the narrowest scopes that cover what your users do. Add scopes when a user needs them. Use wildcards for test environments and power users. For three starting profiles, see Set the user permissions.

Do not use ai:models:* in production. It grants every model added later, and some of those cost more. Grant one provider, such as ai:models:openai:*, or exact models instead. The same rule applies to file formats. Grant the formats your users upload.

If a token does not have a scope the endpoint needs, the API returns 403 Forbidden. The body has the code missing-permissions and the message “The user is missing permissions”. The field data.missingPermissions lists the missing scopes.

To fix the error, add the listed scopes to the auth.ai.permissions claim in your token endpoint, issue a new token, and send the request again. See Error codes for the fields every error carries.

• Models lists the model ids the model permissions refer to.
• Conversations, Actions, and Reviews each have a Permissions section with the scopes that feature needs.
• API reference lists the scope each endpoint requires.