Skip to content

liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-roles-permissions

manage-roles-permissions

Verified

Create roles, assign permissions on objects and pages, and manage site memberships via Headless Admin User and object collaborators APIs. Use when the user asks to add a role, grant permissions, make a page private, share an entry with one user, or control who can view or edit an object's entries.

Manage Roles and Permissions

Create roles and assign the minimum required permissions for objects, pages, and sites.

When to Invoke

  • "Create a Reader role", "add a role that can only view Books"
  • "Grant edit permissions on this object to Site Members"
  • "Make this page visible only to authenticated users"
  • "Give the Sales role permission to add and update Orders"
  • Called by build-site during the roles and ACL phase

Prerequisites

None for roles and grants. The object collaborators API (sharing an entry with one user) needs feature flag LPD-17564 on 2026.Q1 and 2026.Q2, where it defaults to off. From 2026.Q3 the flag is gone and collaborators work without it ("Share an Entry With One User" below).

Workflow

Ship roles and grants in the site initializer tree. Roles go in roles.json, permission grants in resource-permissions.json, users and accounts in user-accounts.json and accounts.json (see rules/site-initializer-format.md). The REST calls below show each payload's shape and serve single changes to a running instance. See liferay-rules.md → "Deliver Through Client Extensions".

Create a Role

curl \
	--data '{
		"name": "<RoleName>",
		"roleType": "regular",
		"name_i18n": {"en_US": "<Role Display Name>"}
	}' \
	--header "Content-Type: application/json" \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-user/v1.0/roles" \
	--user "test@liferay.com:test"

roleType values:

ValueScope
regularAcross the portal; applies to all sites
siteScoped at the site level; membership and permissions are site specific
organizationScoped at the organization level

Save the returned id as <role-id>.

Assign Users to a Role

# Assign a user account to a regular role

curl \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-user/v1.0/roles/<role-id>/association/user-account/<user-id>" \
	--user "test@liferay.com:test"

For role assignment scoped at the site level, use the role association endpoint scoped to the site (there is no /sites/{id}/site-members endpoint). The site is addressed by its numeric <site-id> here. On a regular site, the association also adds the user as a site member:

curl \
	--request POST \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-user/v1.0/roles/<role-id>/association/user-account/<user-id>/site/<site-id>" \
	--user "test@liferay.com:test"

Grant Permissions on an Object Definition

Object level permissions control which roles can create, view, update, or delete entries for that object definition.

There is no /permissions endpoint for an object definition. object-admin declares none (from source), so PUT /o/object-admin/v1.0/object-definitions/<id>/permissions cannot work. The definition DTO's permissions property sets permissions on the definition itself, not on its entries. Grant object level permissions in the initializer tree with resource-permissions.json (the next section and rules/site-initializer-format.md), or in Control Panel → Objects → [Object] → Permissions.

A grant on the role itself works over headless-admin-user instead: PATCH /o/headless-admin-user/v1.0/roles/{roleId} with only {"rolePermissions": [{"actionIds": ["ADD_OBJECT_ENTRY"], "primaryKey": "<companyId>", "resourceName": "com.liferay.object#<definitionId>", "scope": 1}]}. RoleResourceImpl.patchRole calls ResourcePermissionService.addResourcePermission for each listed action, so it only adds: other grants stay, and the role's name, titles, and description are kept (omitted fields fall back to the stored ones). Entries with scope 4 (individual) are skipped. Read the role first, GET /roles/{roleId}, whose rolePermissions lists every grant the role holds (resourceName, scope, actionIds), to compare before writing; on the Guest role that is tens of thousands of rows. It cannot revoke: there is no remove path in this method. Verified on 2026.Q2: Guest got ADD_OBJECT_ENTRY at the company level on a new object, and an anonymous GET /o/c/<plural> still answered totalCount: 0.

Common actionIds for object definitions:

Action IDMeaning
ADD_OBJECT_ENTRYCreate entries
VIEWView the object in site and admin UI
PERMISSIONSManage permissions on this object

Public Form: Let Guest Create Without Reading

A site role never grants the add on an object scoped at the company level. The add is checked in group 0, where no site role counts, so an ADD_OBJECT_ENTRY grant at the company level for Site Member renders a Form Container for the site's members and then fails every submission silently. Grant it to a regular role (Guest, User, or a role the members hold). Verified on 2026.Q3; see manage-form-containers → "First: Grant ADD_OBJECT_ENTRY".

An object registers two resource names and the action decides which to grant on — ADD_OBJECT_ENTRY is not on the [$OBJECT_DEFINITION_CLASS_NAME:…$] resource, and granting it there silently does nothing. rules/guest-access.md has the table and the guest-unsupported set; it is always loaded, so read it there rather than guessing here.

For an anonymous registration, enquiry, or application form, grant creation on the private object and viewing only on the public one. In the initializer tree (resource-permissions.json, see rules/site-initializer-format.md for the scope integers):

[
	{
		"actionIds": ["ADD_OBJECT_ENTRY"],
		"primKey": "0",
		"resourceName": "com.liferay.object#[$OBJECT_DEFINITION_ID:<PrivateObject>$]",
		"roleName": "Guest",
		"scope": "1"
	},
	{
		"actionIds": ["VIEW"],
		"primKey": "0",
		"resourceName": "[$OBJECT_DEFINITION_CLASS_NAME:<PublicObject>$]",
		"roleName": "Guest",
		"scope": "1"
	}
]

Do not add VIEW on the object that receives submissions. Those rows hold whatever the visitor typed — names, emails, addresses — and VIEW at the company level publishes all of them to anonymous users. Write only is the correct posture for a public form, and it is why any count or aggregate over that object has to be denormalized onto the public object rather than computed in the browser (see manage-pages → "Mapping Limits").

Grant Permissions on Object Entries

Per entry role grants are the entry's /permissions endpoint. To open one entry to one user, share it instead ("Share an Entry With One User" below).

The entry /permissions PUT, like every Vulcan /permissions PUT, takes a bare JSON array of Vulcan Permission items: actionIds, roleExternalReferenceCode, roleName, roleType. The DTO has no roleId field (from source), and a {"permissions": [...]} wrapper returns 400 "Unable to map JSON path". Copy the field values from a GET on the same endpoint.

The PUT is a full replace: read the current grants first and send again every role that should keep access — Owner and administrator roles included — or they are silently dropped.

curl \
	--data '[
		{
			"actionIds": ["UPDATE", "VIEW"],
			"roleExternalReferenceCode": "<role-erc>",
			"roleName": "<role-name>",
			"roleType": "regular"
		}
	]' \
	--header "Content-Type: application/json" \
	--request PUT \
	--silent \
	--url "http://localhost:${PORT}/o/c/<pluralLabel>/<entry-id>/permissions" \
	--user "test@liferay.com:test"

Common actionIds for object entries:

Action IDMeaning
VIEWRead the entry
UPDATEEdit the entry
DELETEDelete the entry
PERMISSIONSManage permissions on this entry

Share an Entry With One User (Collaborators)

Liferay Sharing gives one user access to one object entry, beside the role grants. The CMS's "Share" is this. On 2026.Q1 and 2026.Q2 these endpoints need LPD-17564 (see "Prerequisites"). Verified on 2026.Q3 on a CMS Space entry:

  • The call: PUT /o/c/<plural>/scopes/<scope>/by-external-reference-code/<erc>/collaborators/by-type/User/<userId> (or /o/c/<plural>/<id>/collaborators/by-type/User/<userId>) with {"actionIds": ["DOWNLOAD", "VIEW"], "type": "User"}. Sharing actions are VIEW, DOWNLOAD, UPDATE, ADD_DISCUSSION; "share": true lets the user reshare. GET on the same path answers 404 when there is no share.
  • Not by email address: …/collaborators/by-email-address/<email> makes an Email collaborator, which may only VIEW (400 "Collaborators of type \"Email\" can only be granted the VIEW action"), even for an existing user's address.
  • The collection takes no PUT. POST …/collaborators replaces the whole list (it deletes collaborators left out).
  • What a share opens: the entry over REST (by ID, by ERC, in the scoped list), its file by its /documents URL (200 for the shared user; another user 401, an anonymous visitor 404), search, and a link to the file held by another object's Attachment field, which follows the file's own entry, not the linking entry.
  • On a custom object's entry (not a CMS file type), DOWNLOAD cannot be shared. {"actionIds": ["DOWNLOAD", "VIEW"]} answered 403, even for the administrator, since the object has no DOWNLOAD action. Share VIEW alone: a role's DOWNLOAD_<FIELD> grant at the company level still gives the shared user the attachment's link. A share's UPDATE lets the user PATCH the entry.
  • Every write notifies, an identical one too. Each PUT sends the user a website notification, " has shared with you for viewing." (language key x-has-shared-x-with-you-for-x), and attempts an email. So compare with the GET first and write only on a difference. Unlike the CMS's notifications about Space membership, these render over headless-user-notification: an admin can list them (GET /o/headless-user-notification/v1.0/user-accounts/<userId>/user-notifications) and mark them read (PUT /user-notifications/<id>/read, 204).
  • A share is indexed as a SharingEntry, with no permission filter. Its document holds the entry's title, dates, userId, and toUserId, and any signed in user's /o/search/v1.0/search finds that title and those dates (no link, no content). Leave com.liferay.sharing.model.SharingEntry out of a blueprint's searchable types where the titles matter.
  • Deleting the entry deletes its shares, their search documents, and their notifications. A CMS entry's first DELETE only moves it to the Space's trash (status 8, still readable by ERC); a second DELETE removes it.

Depot Roles (Spaces and Asset Libraries)

A Space or asset library has its own role type, roleType: depot (role_.type_ 5). Two of these roles are given implicitly by DepotRoleContributor (from source):

RoleERCWho gets it
Asset Library MemberL_ASSET_LIBRARY_MEMBERMembers of the library or Space itself
Asset Library Connected Site MemberL_ASSET_LIBRARY_CONNECTED_SITE_MEMBERMembers of any Site the library is connected to, including members only through a user group (the user bag counts inherited groups)

Grant the second one on items and folders to say "whoever belongs to the connected Site", with the same bare Permission[] body ("roleType": "depot"). Space entries also start with a User VIEW grant, which opens them to every signed in user, so a restricted audience means a full replace without it.

Grant Permissions on a Site Page

Page level permissions control visibility and edit access.

Same body shape as for object entries: a bare Permission[] array (putSiteSitePagePermissionsPage, from source). Same full replace semantics.

curl \
	--data '[
		{
			"actionIds": ["VIEW"],
			"roleExternalReferenceCode": "<guest-role-erc>",
			"roleName": "Guest",
			"roleType": "regular"
		},
		{
			"actionIds": ["UPDATE", "VIEW"],
			"roleExternalReferenceCode": "<role-erc>",
			"roleName": "<role-name>",
			"roleType": "regular"
		}
	]' \
	--header "Content-Type: application/json" \
	--request PUT \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-site/v1.0/sites/<site-erc>/site-pages/<page-erc>/permissions" \
	--user "test@liferay.com:test"

To make a page visible only to authenticated users, remove the VIEW permission from the Guest role. To make it fully private, also remove it from the User role and grant VIEW only to the target role.

Verify Roles and Permissions

# List roles

curl \
	--silent \
	--url "http://localhost:${PORT}/o/headless-admin-user/v1.0/roles" \
	--user "test@liferay.com:test" \
	| jq '[.items[] | {id, name, roleType}]'

# Check permissions on an object entry (object definitions have no /permissions endpoint)

curl \
	--silent \
	--url "http://localhost:${PORT}/o/c/<pluralLabel>/<entry-id>/permissions" \
	--user "test@liferay.com:test" \
	| jq '.items'

Checking a user's roles on the client: they are scoped, not flat. GET /o/headless-admin-user/v1.0/my-user-account returns roles split across roleBriefs (regular), accountBriefs[].roleBriefs, organizationBriefs[].roleBriefs, siteBriefs[].roleBriefs, and userGroupBriefs[].roleBriefs. Code that checks only the roleBriefs at the top level misses every account/site/org role — flatten all five before testing for a role name. Also note a plain account member shows an empty accountBriefs[].roleBriefs (membership is implicit, not a role).

roleBriefs lists only the roles the caller can view, and a brief's name is the role's title. UserResourceDTOConverter._toRoleBriefs drops every role the caller lacks VIEW on (:522–537), and RoleBriefUtil sets name to the title and key to the role's name (:25–32). Verified on 2026.Q3: a user's own my-user-account listed only User although the user held another regular role, and listed it as {"name": "<role title>", "key": "<role name>"} once that role got VIEW on itself at individual scope. An administrator sees every role. So code that reads a user's roles with that user's own token needs that VIEW, and must match titles or read key.

Permission Design Principles

  • Assign the minimum set of actionIds that satisfies the workflow requirement.
  • Use site roles (not regular roles) for permissions that should vary per site.
  • The Guest role represents unauthenticated visitors. Remove VIEW from Guest to require login.
  • The User role represents any authenticated user. Remove VIEW from User and grant to a specific role to restrict access.
  • Grants at the company level on AccountEntry read no entry under account restriction. A regular role holding VIEW, UPDATE, and the user actions on every account still gets 404 on entries under account restriction: the restriction admits the account's members and administrators, not holders of account permissions. Give such a role entry access by membership, or by an explicit object grant, which then opens every account's entries to it. Verified on 2026.Q2.
  • A Site Administrator or Site Owner needs no grant on an object scoped at the site level, and none can be withheld. They are group admins, and AdvancedPermissionChecker answers true for a group admin on any resource of the group after the role check fails. Verified on 2026.Q2 with a user given only the site role Site Administrator, no membership, and no grant: GET showed every action (update, delete, permissions, share), PATCH and DELETE worked on an entry another user owns, and POST answered 200 without ADD_OBJECT_ENTRY. Only readOnly fields bind them, and those not on create. Removing a grant from these roles therefore changes nothing; route such writes through a module if they must be checked.

Creating Users via API — Clear Password and Terms Flags

A user created through the Headless Admin User API must reset the password and accept the terms of use at first login. Until then, the new user's REST calls return silent 403s.

The headless UserAccount DTO cannot clear those flags: it has no agreedToTermsOfUse or passwordReset property (from source), and a create that sends them returns 400 "The properties [passwordReset,agreedToTermsOfUse] are unknown" (verified on 2026.Q3). The reliable way to avoid the first login 403 trap is the preboot bootstrap (terms.of.use.required=false, passwords.default.policy.change.required=false) covered in workspace-init.

Success Signal

TODO / inferred — verify against a running bundle. The Verify Roles and Permissions step above (role listed; granted actionIds present; a user holding only that role is allowed the granted actions and denied the rest) is the observable completion check; confirm on a live bundle.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall