Developers

Plugins

Plugin capabilities — let administrators choose which role can do what

Declare a plugin's own permissions in the manifest, and administrators tick them per role under Users → Permissions — used by routes, admin pages, actions, content types and user.can() in code

8 min readLast updated

View as Markdown

On this page

A plugin can declare permissions of its own, such as "View statistics", "Publish docs" or "Change the API key", and the site's administrators choose which role gets which under Users → Permissions → 🔌 Plugin permissions. The plugin's code no longer hard-codes role names (available since Anasaki Studio 2.0.6, for JavaScript, service and WASM plugins).

1. Declare them in manifest.json#

{
  "id": "page-translate",
  "minCore": "2.0.6",
  "capabilities": [
    { "id": "manage",
      "label": { "th": "ตั้งค่าการแปลภาษา", "en": "Manage page translation" },
      "description": { "th": "เปิดหน้า แปลภาษา (ตั้งค่า) และแก้โหมด", "en": "Open the settings page and change the mode" },
      "default": ["administrator", "editor"] },
    { "id": "api_key",
      "label": { "th": "แก้ Google API Key", "en": "Change the API key" },
      "default": ["administrator"] }
  ]
}
FieldRules
idStarts with a-z, then a-z 0-9 _, 2–31 characters, unique in the plugin. The permission's full name is <plugin id>.<id>, e.g. page-translate.manage
label{th, en} or a string, up to 80 characters, shown on the Permissions page and at install
descriptionOptional {th, en}, up to 300 characters
defaultRoles that get the permission on first install (administrator editor author contributor subscriber or custom roles), at most 20

At most 30 capabilities per plugin, and the Store checks the same rules at upload (Store 1.2.2 and later).

2. Using them in code#

A plugin may refer only to its own capabilities (<own id>.*) and system permissions — referring to another plugin's capability fails at registration.

access lists#

Add 'cap:<capability>' alongside role names; every role with that capability passes.

site.adminPage('settings', { label: { th: 'แปลภาษา (ตั้งค่า)', en: 'Page Translate' }, access: ['cap:page-translate.manage'], render });
site.action('saveApiKey', { access: ['cap:page-translate.api_key'], input: { apiKey: 'text?' }, run });
site.route('GET /reports/export', { access: ['cap:reports.export', 'administrator'] }, handler);

Works with site.route, site.page, site.collection, site.action, site.adminPage, site.dashboardWidget, site.adminNotice and access.edit of content types. Administrators can still override under Site Code → Access.

Checking in code#

run: ({ user }) => {
  if (!user?.can('page-translate.api_key')) return { message: 'Not allowed to change the API key', errors: { form: 'forbidden' } };
  // …
}
site.can(user, 'reports.export');   // user is null → false
user.caps;                          // system permissions + this plugin's capabilities the user has

Hiding buttons or forms with user.can() is cosmetic only — always check again in access or in the action's run.

Plugin content types#

site.postType('docs_doc', {
  label: { th: 'เอกสาร', en: 'Docs' },
  caps: { edit: 'docs.edit', publish: 'docs.publish' },   // who writes/edits and who publishes
});
  • caps.edit replaces the default list of editor roles
  • caps.publish restricts publishing (without it, anyone who can edit can publish). Published articles can be edited or deleted only by those who can publish
  • REST /api/v1/posts and db.posts enforce this, and GET /api/v1/post-types reports canEdit / canPublish for the calling user

Service / WASM plugins#

  • Admin pages: set service.admin[].cap to "<own id>.<id>"
  • The user data sent along (the X-Anasaki-User header and the plugins.call body) has user.caps, combining system permissions and this plugin's capabilities

3. Supporting older Anasaki Studio versions#

Versions before 2.0.6 don't know capabilities (they simply skip it) but do not accept cap: in access. Check for site.can first:

const CAPS = typeof (site as any).can === 'function';            // 2.0.6+
const ACCESS_MANAGE = CAPS ? ['cap:page-translate.manage'] : ['editor'];
site.adminPage('settings', { label: 'Page Translate', access: ACCESS_MANAGE, render });

If you don't need older versions, set "minCore": "2.0.6" or later and use cap: directly.

4. Install, update and uninstall#

  • Install or update: capabilities the site has never seen go to the roles in default; existing ones keep what the administrator set. An update therefore never gives back a capability the administrator removed
  • An update that drops a capability, or uninstalling: it disappears from every role; the roles' other permissions stay. On reinstall, only never-seen capabilities get their defaults
  • Administrators always have every permission, and plugin capabilities apply only while the plugin is installed
  • The install dialog lists the capabilities the plugin will add, so administrators see them before installing

5. Naming capabilities well#

  • Split by what people do, not by screen: view, edit, publish, manage, export
  • Keep risky actions separate, such as changing an API key or deleting all data, with default set to administrator only
  • Write label and description for administrators who don't code — that text is all they see on the Permissions page

Full details in Plugin API; the official Docs and Analytics plugins are examples that use their own capabilities.