@zealamic/payload-plugin-rbac

Centralized role-based access control (RBAC) for Payload CMS v3 (payload ^3.84.1). Not compatible with Payload 2.x.

Permissions live in the database (feature + action), are assigned to roles, and enforced via reusable access helpers — editable in Admin without redeploying policy code.

Row-level access (dataScope): list collection slugs in targetCollections for auto ownership field + create hook, then wire getPermissionAccess. → COLLECTIONS — targetCollections · manual setup → UTILS

---

Documentation

Guide	Read when you need to…
COLLECTIONS	Plugin collections, users augmentation, dataScope, permission matrix, field/access overrides
UTILS	getPermissionAccess, data-scope filters, field merge helpers
TRANSLATIONS	Admin labels, select options, matrix UI strings (en, vi, …)
CUSTOM_COMPONENTS	Custom matrix checkboxes / search input (client field component)

Typical flow: install → register plugin with targetCollections (COLLECTIONS) → run migration → seed RBAC data (COLLECTIONS) → add getPermissionAccess on app collections (UTILS) → translate Admin UI (TRANSLATIONS).

Demos in this repo: dev/rbac.ts, dev/collections/posts.ts, dev/components/role-permission-matrix-field.tsx.

---

Key features

• Five RBAC collections — features, actions, permissions, roles, join table (details)
• Multi-role users — union of enabled grants across assigned roles
• Granular permissions — any featureCode + actionCode pair (helpers)
• Data scope — own / hierarchy / all; use targetCollections for ownership field + hook, or add manually (UTILS)
• targetCollections — auto-add hidden ownership field + create hook on app collections (COLLECTIONS)
• Auth users slug — config.admin.user (default users) for hierarchy + options.usersCollectionSlug
• Permission matrix — role update UI; syncs draft → roles-permissions on save
• Reorder drawers — drag-and-drop sortOrder for permission features and actions on each collection list view
• Custom matrix UI — optional client field component + render props (CUSTOM_COMPONENTS)
• TypeScript — typed plugin config and exported helpers/types from the main package
• i18n — plugin translations merged into Payload i18n (guide)

---

Installation

npm install @zealamic/payload-plugin-rbac
# or: yarn add / pnpm add @zealamic/payload-plugin-rbac

---

Quick start

1. Register the plugin

import { payloadPluginRBAC } from "@zealamic/payload-plugin-rbac";

export default buildConfig({
  plugins: [
    payloadPluginRBAC({
      autoModifyUsersCollection: true, // roles, isSuperAdmin, parent, default user access
      targetCollections: ["posts"], // ownership field + create hook — see step 4
      // collections: { ... }   → https://github.com/zealamic/payload-plugin-rbac/blob/main/docs/COLLECTIONS.md
      // translations: { ... } → https://github.com/zealamic/payload-plugin-rbac/blob/main/docs/TRANSLATIONS.md
      // components: { rolePermissionMatrixField: "..." } → custom matrix Field (client module)
    }),
  ],
});

2. Migration

After adding the plugin (and especially after changing targetCollections), update your database schema:

yarn payload migrate:create
yarn payload migrate

(npm run / pnpm equivalents work too.)

Run migrate:create when new fields are added to collections (e.g. first time you list a slug in targetCollections). Then migrate to apply pending migrations.

Bootstrap a super admin: RBAC collections are restricted to super admins by default. Set isSuperAdmin: true on at least one user (via seed script, Local API, or direct database update) before you can manage roles, permissions, and the permission matrix in Admin.

→ COLLECTIONS — Bootstrap super admin

3. Seed RBAC data (Admin or script)

1. permission-features — e.g. posts, users (code = featureCode in access helpers); use Reorder on the list view to set row order in the matrix
2. permission-actions — e.g. create, read, update, delete (main / sub types); use Reorder to set main column and sub-action order
3. permissions — one row per feature + action pair (status: active)
4. roles — set dataScope; open update screen, configure matrix → Save
5. users — assign roles; bootstrap isSuperAdmin via seed/API

→ Full reference: COLLECTIONS

4. Protect app collections

Recommended: list slugs in targetCollections — the plugin adds a hidden ownership field (createdBy text by default) and a create hook. You only wire getPermissionAccess on the collection. Full options → COLLECTIONS — targetCollections.

// payload.config.ts
payloadPluginRBAC({
  targetCollections: ["posts"],
});

// collections/posts.ts — no manual createdBy field or hook needed
import type { CollectionConfig } from "payload";
import { getPermissionAccess } from "@zealamic/payload-plugin-rbac";

export const Posts: CollectionConfig = {
  slug: "posts",
  access: {
    read: getPermissionAccess({ featureCode: "posts", actionCode: "read", options: {} }),
    create: getPermissionAccess({ featureCode: "posts", actionCode: "create" }),
    update: getPermissionAccess({ featureCode: "posts", actionCode: "update", mode: "modify" }),
    delete: getPermissionAccess({ featureCode: "posts", actionCode: "delete", mode: "modify" }),
  },
  fields: [{ name: "title", type: "text", required: true }],
};

After adding or changing targetCollections, run yarn payload migrate:create then yarn payload migrate.

Manual setup (visible fields, custom layout, or full control): add ownership field + create hook yourself → UTILS — Ownership field · relationship demo: dev/collections/posts.ts

Access order: no user → deny · super admin → allow · else → matrix permission (+ scope when options / mode: "modify").

---

Reorder overview (features & actions)

List views for permission-features and permission-actions include a Reorder drawer to set sortOrder (hidden on edit forms). Order drives the role permission matrix: features → rows, main actions → columns, sub actions → checkbox order under each row.

Step	Action
Features	Permission Features → Reorder → drag → Save order
Actions	Permission Actions → Reorder → pick Main or Sub → drag → Save order

API: POST /api/permission-features/reorder · POST /api/permission-actions/reorder — body { "sortedItems": [{ "id": "…", "sortOrder": 0 }] }. Requires update access (super admin by default). Details → COLLECTIONS · labels → TRANSLATIONS — Reorder drawers.

---

Plugin options

Option	Default	Description
disabled	false	Skip runtime i18n/onInit wiring; collections still register in schema
autoModifyUsersCollection	true	Add RBAC fields, parent-path hooks, and default access on the auth users collection
targetCollections	—	Auto ownership field + create hook on listed app collections → COLLECTIONS
translations	—	Admin + matrix i18n → TRANSLATIONS
collections	—	Per-collection fields / access / admin overrides → COLLECTIONS
components.rolePermissionMatrixField	default client export	Import-map path to a custom matrix Field component (client module)

Types import from the main entry:

import type {
  RBACTranslations,
  PayloadPluginRBACConfig,
  TargetCollection,
} from "@zealamic/payload-plugin-rbac";

---

Exported helpers (summary)

Full reference: UTILS

Function	Purpose
getPermissionAccess	Unified access: permission-only, read Where, or modify per-document
targetCollections (plugin config)	Quick ownership field + hook — COLLECTIONS
getCreatedByRelationshipField / createCreatedByOnCreateBeforeChangeHook	Manual ownership field + hook → UTILS
resolveUsersCollectionSlug	Same admin.user → slug resolution as the plugin
getSuperAdminAccess	Super admin only (default on RBAC collections)
getAuthenticatedOrSuperAdminAccess	Owner or super admin
canAccessDocumentByDataScope	Low-level single-document RBAC + scope check
resolveEffectiveDataScope / getHierarchyVisibleUserIds	Scope resolution
getDataScopeReadWhere / mergeDataScopeWhere	Query filters
getMergedFieldAffectingData / getArrayOfMergedFieldAffectingData	Field merge for overrides

Constants: CONSTANTS.ROLE.DATA_SCOPE, CONSTANTS.PERMISSION_ACTION.TYPE, etc.

---

Package exports

Import	Contents
@zealamic/payload-plugin-rbac	payloadPluginRBAC, utils, constants, TypeScript types
@zealamic/payload-plugin-rbac/client	RolePermissionMatrixClient, PermissionActionReorderClient, PermissionFeatureReorderClient, createRolePermissionMatrixClient, and related types

---

Images from demo

Reorder screenshots: Reorder overview above.

---

License

MIT

---

If this plugin helps your team ship safer access control with less friction, thank you for giving it a place in your stack.