Skip to content
Merulan

Roles and Permission bundles

Roles and Permission bundles grant actions through time-bound access or Group membership, while field grants remain separate.

Roles and Permission bundles name which actions a caller may use. Governance owns these grants. Each grant has a scope.

Ownership

A Role defines actions and a time limit for access. A Permission bundle links a Group to action policies. It can carry field grants for its Members. Open Roles at /governance/roles and Permission bundles at /governance/bundles in the Console. Choose a Role for short-lived access. Inspect a Bundle when access follows Group membership.

Product authors declare a Permission bundle with construct.permissionBundles(...) and attach it to a tenant Group key with construct.permissionBundleGrants(...). Installing the Product creates the Group and its action policies. The Group name is a key, not a permission. A Product may name an existing platform administrator bundle in a grant without copying its actions. The older construct.capabilityBundles and construct.capabilityBundleGrants builders are retired and refuse by name.

Lifecycle

A Role request needs approval before the requester can activate it. Approval alone does not activate a Role. A human request needs another approver. An agent request within the Role's default time limit can be approved without one. The grant cannot outlast the Role's maximum time limit or the agent's Run limit. Expiry or revocation ends the active grant.

A Role update creates a new version. Retirement prevents new requests while keeping history. Permission bundle changes alter its action policies or Members. A Member joining a Bundle also inherits its field grants. Read the Bundle's scope and effective grants before adding someone to its roster.

Boundaries

A Role grants actions, not field grants. Field Access still checks each field's required grants and Purpose. Role activation grants the actions of the requested Role. The public request does not accept a permission subset. Permission bundles can hold field grants. Two grants that allow the same action can therefore expose different fields.

Failures

A Role request can expire or be denied before activation. Self-approval is refused. Separation of Duties checks held Roles when access is activated. A conflicting pair is refused. A missing required Purpose also blocks activation. Repeating approval does not fix those checks or turn an expired request into live access.

Recovery

Read the Role request state before making another access request. For an expired request, seek a fresh approval. For a conflict, have the administrator resolve the held Roles or required Purpose. The Role activation contract owns the call and its errors. Confirm the active grant through permitted readback before treating approval as usable access.

Export and delegation

Roles and Permission bundles group the actions a member may take. Merulan retains each role, the bundles inside it, who holds it, and the check on every action. An outside directory may assign groups. A group counts only after Merulan maps it to a role. An exported role keeps its name and bundles but grants nothing in another system.

  • The Field Access model explains which grants and Purposes a Role cannot replace.
  • The access workflow applies the Role lifecycle to a request and checks its result.