# 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

Source: https://anasaki.live/docs/en/developers/plugin-capabilities

A plugin can declare **permissions of its own**, such as &#34;View statistics&#34;, &#34;Publish docs&#34; or &#34;Change the API key&#34;, 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

```json
{
  &#34;id&#34;: &#34;page-translate&#34;,
  &#34;minCore&#34;: &#34;2.0.6&#34;,
  &#34;capabilities&#34;: [
    { &#34;id&#34;: &#34;manage&#34;,
      &#34;label&#34;: { &#34;th&#34;: &#34;ตั้งค่าการแปลภาษา&#34;, &#34;en&#34;: &#34;Manage page translation&#34; },
      &#34;description&#34;: { &#34;th&#34;: &#34;เปิดหน้า แปลภาษา (ตั้งค่า) และแก้โหมด&#34;, &#34;en&#34;: &#34;Open the settings page and change the mode&#34; },
      &#34;default&#34;: [&#34;administrator&#34;, &#34;editor&#34;] },
    { &#34;id&#34;: &#34;api_key&#34;,
      &#34;label&#34;: { &#34;th&#34;: &#34;แก้ Google API Key&#34;, &#34;en&#34;: &#34;Change the API key&#34; },
      &#34;default&#34;: [&#34;administrator&#34;] }
  ]
}
```

| Field | Rules |
| --- | --- |
| `id` | Starts with `a-z`, then `a-z 0-9 _`, 2–31 characters, unique in the plugin. The permission's full name is **`.`**, e.g. `page-translate.manage` |
| `label` | `{th, en}` or a string, up to 80 characters, shown on the Permissions page and at install |
| `description` | Optional `{th, en}`, up to 300 characters |
| `default` | Roles 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** (`.*`) and system permissions — referring to another plugin's capability fails at registration.

### `access` lists

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

```ts
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

```ts
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

```ts
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 `&#34;.&#34;`
- 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:

```ts
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 `&#34;minCore&#34;: &#34;2.0.6&#34;` 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](/docs/en/developers/plugin-api); the official **Docs** and **Analytics** plugins are examples that use their own capabilities.
