#Authorize Role Menus

Role-menu authorization answers the common admin-system question: which menus, views, actions, APIs, and response fields a role can use.

It does not bind users automatically. First save menu grants on a role, then use userRoles.assign() or userRoles.set() to give that role to a user. Every generated API permission still resolves to invoke + apiResource internally; the role-menu API keeps that detail traceable without asking administrators to write low-level rules by hand.

#Minimal Admin-Page Flow

If you are building a role authorization page, think in this order:

The most common admin page saves the whole authorization tree: read getAuthorizationTree(), let the user select items, build assignments, call preview({ operation: 'set', assignments }), then call set() after confirmation.

#How the Objects Connect

Text equivalent. The menu config is only the grantable resource inventory. The role authorization UI selects menus, views, load APIs, actions, and response fields from that inventory. preview only shows impact; grant, deny, or set writes role-menu authorization. After userRoles binds the role to a user, subject.menus projects that user's visible menu tree, action state, and returnable response fields.

The main line is:

menu config → role-menu authorization → user-role binding → subject runtime projection

Do not treat MenuConfigInput as the permission result. It is the inventory that can be granted. Role grants and user-role assignments decide what a user can access.

#How UI Selections Become selection

Think of selection as “the capabilities selected in this admin form submission.” You do not need to memorize the whole type first; start with this mapping:

#Build a Selection

The selection below grants the order-operator role the orders list view in the admin config, includes the view's load API and actions, and allows only orderNo and status in the orders response.

const selection = {
  configId: 'admin',
  views: ['orders-list'],
  responseFields: [{
    apiResource: 'api:GET:/api/orders',
    target: 'items',
    fields: ['orderNo', 'status'],
  }],
  include: {
    loads: true,
    actions: true,
    responseFields: 'none',
  },
};

const assignments = [
  { effect: 'allow', selection },
];

Defaults are descendants: false, loads: true, actions: false, and responseFields: 'none'. Selecting a view therefore grants page load APIs by default, but does not automatically grant actions or response fields. Use include.responseFields: 'all' when selecting a view should grant every declared response field. Admin systems often prefer explicit fields so newly added sensitive fields are not automatically exposed to old roles.

For paginated or nested responses, write target. For an API returning { items, total }, target: 'items' means the grant applies to fields inside each items row. The mode value 'all' grants every declared field. Pagination metadata such as total belongs in response config preserve, not in role field grants.

#Preview, Then Commit

Unlike creating menus, views, or API records, role-menu authorization changes what a role can actually access and can affect many users immediately. It therefore keeps explicit preview before commit. Ordinary administrators do not need to understand revision internals; the role editor previews impact first, then submits the same selection with the preview credentials.

Preview first:

const scoped = pc.scope(
  { tenantId: 'acme', appId: 'admin' },
  { actorId: 'admin', requestId: 'req-set-order-operator-menu' },
);

const preview = await scoped.roles.menuPermissions.preview(
  'order-operator',
  { operation: 'set', assignments },
);

if (!preview.executable) {
  throw new Error('ROLE_MENU_PERMISSION_CONFLICT');
}

When there are no conflicts, the admin UI mainly cares about executable: true, affected users, and the authorization records that would be generated. Read the response like this:

{
  "executable": true,
  "previewToken": "preview_...",
  "summary": {
    "affectedUsers": { "total": 1, "sampleIds": ["u-menu"] },
    "grants": { "total": 1 },
    "removals": { "total": 0 }
  }
}

After confirmation, pass the same assignments and the preview credentials to the write method:

const saved = await scoped.roles.menuPermissions.set(
  'order-operator',
  assignments,
  {
    ...preview.expected,
    previewToken: preview.previewToken,
  },
);

{
  "changed": true,
  "data": {
    "inserted": 1,
    "updated": 0,
    "unchanged": 0,
    "deleted": 0,
    "conflicted": 0,
    "samples": {
      "total": 1,
      "items": [{ "id": "grant_...", "outcome": "inserted" }]
    }
  }
}

menuPermissions.preview(roleId, change) reads only and computes sources, affected users, and conflicts. menuPermissions.set(roleId, assignments, options) writes the current admin selection as the role's complete direct menu authorization. Execution must include the preview's expected vector and previewToken.

inserted/updated/deleted/unchanged/conflicted is the batch-write summary for this save. samples.items is only a small troubleshooting sample, not the permission-checking API. For detailed generated sources, response fields, and affected users, read the preview summary first.

#Grant, Deny, Revoke, or Replace

These four methods are not equal in day-to-day admin UI work. A normal role authorization page usually uses set() to save the whole tree; the other methods are for append-only grants, explicit overrides, or precise deletion.

set() replaces menu grants only. It does not replace manual roles.allow() or roles.deny() rules, and it does not change user-role bindings. Every write method requires a matching preview operation; revoke() removes grants by grantId.

#Read Role Authorization

const direct = await scoped.roles.menuPermissions.getDirect('order-operator');
const effective = await scoped.roles.menuPermissions.getEffective('order-operator');
const tree = await scoped.roles.menuPermissions.getAuthorizationTree(
  'order-operator',
  { configId: 'admin' },
);

Exact return types live in the Role Menu Permissions API. For this guide, remember: getAuthorizationTree() is for the administrator editor. User navigation uses subject.menus.getViewTree({ configId }).

#User Runtime Result

#Verify Menus and Actions

After saving authorization, bind the role to a user and read the menu tree and action state from that user's subject:

await scoped.userRoles.assign('u-menu', 'order-operator');

const menus = pc.forSubject({
  userId: 'u-menu',
  scope: { tenantId: 'acme', appId: 'admin' },
}).menus;

const tree = await menus.getViewTree({ configId: 'admin' });
const actions = await menus.getActionMap({ configId: 'admin', viewId: 'orders-list' });
const state = await menus.getViewState({ configId: 'admin', viewId: 'orders-list' });

#Project API Responses

Before a business API returns data, project response fields with the same subject:

const projected = await menus.filterResponse('api:GET:/api/orders', {
  items: [{ orderNo: 'O-1001', status: 'paid', amount: 88, internalCost: 51 }],
  total: 1,
});
const projectedData = projected.data;

{
  "tree": [{ "id": "orders", "enabled": true }],
  "actions": { "export": { "visible": true, "enabled": true } },
  "state": { "allowed": true, "navigationReachable": true },
  "projectedData": {
    "items": [{ "orderNo": "O-1001", "status": "paid" }],
    "total": 1
  }
}

filterResponse(apiResource, payload) first checks whether the current user can invoke the API resource, then projects the payload according to response-field grants. The projected payload is in projected.data. Ungranted fields are removed; missing invoke permission fails instead of returning unprojected data.

#Role, User, and Menu Boundaries

See the runnable menu admin example and the Role Menu Permissions API.