Features

Permission Groups

Groups are a purely display-layer feature. They help you sort permissions into logical buckets (for example, posts, users, billing) so your admin UI can render them without hand-maintaining a mapping file. Groups have no effect on authorization decisions.

The Column

The permissions table ships with an optional, nullable, indexed group column. Set it when you create the permission:

await Permission.findOrCreate('posts.publish', { group: 'posts' });
await Permission.findOrCreate('posts.archive', { group: 'posts' });
await Permission.findOrCreate('users.invite', { group: 'users' });
await Permission.findOrCreate('system.debug'); // no group

Querying By Group

const postPermissions = await Permission.findByGroup('posts');
// Permission[] filtered by { group: 'posts' }

Rendering Grouped For The UI

const grouped = await Permission.groupedBy();
// {
//   posts: [Permission, Permission],
//   users: [Permission],
//   ungrouped: [Permission],
// }

Permission.groupedBy() reads every permission, groups them by the configured columns.group value, and returns a plain object. Permissions without a group go under ungrouped so your UI can render them in a fallback section.

You can pass a different column to groupedBy(column) if you have migrated permissions into another bucket key:

await Permission.groupedBy('category');

Example: Admin Checkboxes

const grouped = await Permission.groupedBy();

Object.entries(grouped).forEach(([group, permissions]) => {
  console.log(`## ${group}`);
  permissions.forEach((permission) => {
    console.log(`- ${permission.name}`);
  });
});

In a React/Vue admin panel this pattern drops directly into a grouped checkbox list — one section per group, with rows of permission toggles.

Renaming The Column

If your application already stores a "scope" or "category" column, override the config:

// config/permissions.js
export default {
  columns: {
    group: 'category',
  },
};

Permission.findByGroup(value) and Permission.groupedBy() read the column name from the live config, so changing it once updates every call site.

Things Groups Do NOT Do

They do not grant permissions. A user with the posts "group" is not a thing. Assign roles or individual permissions as usual.
They do not cascade. Renaming a group on one permission does not update siblings automatically.
They are not enforced unique per-name. The same permission name can exist only once, but groups can contain as many permissions as you like.