liferay/liferay-portal / workspaces/clarity-solution-workspace/.agents/skills/manage-roles-permissions
manage-roles-permissions
VerifiedCreate 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-siteduring 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 inresource-permissions.json, users and accounts inuser-accounts.jsonandaccounts.json(seerules/site-initializer-format.md). The REST calls below show each payload's shape and serve single changes to a running instance. Seeliferay-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:
| Value | Scope |
|---|---|
regular | Across the portal; applies to all sites |
site | Scoped at the site level; membership and permissions are site specific |
organization | Scoped 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
/permissionsendpoint for an object definition.object-admindeclares none (from source), soPUT /o/object-admin/v1.0/object-definitions/<id>/permissionscannot work. The definition DTO'spermissionsproperty sets permissions on the definition itself, not on its entries. Grant object level permissions in the initializer tree withresource-permissions.json(the next section andrules/site-initializer-format.md), or in Control Panel → Objects → [Object] → Permissions.
A grant on the role itself works over
headless-admin-userinstead: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.patchRolecallsResourcePermissionService.addResourcePermissionfor 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 withscope4(individual) are skipped. Read the role first,GET /roles/{roleId}, whoserolePermissionslists 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 gotADD_OBJECT_ENTRYat the company level on a new object, and an anonymousGET /o/c/<plural>still answeredtotalCount: 0.
Common actionIds for object definitions:
| Action ID | Meaning |
|---|---|
ADD_OBJECT_ENTRY | Create entries |
VIEW | View the object in site and admin UI |
PERMISSIONS | Manage 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_ENTRYgrant 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; seemanage-form-containers→ "First: GrantADD_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 ID | Meaning |
|---|---|
VIEW | Read the entry |
UPDATE | Edit the entry |
DELETE | Delete the entry |
PERMISSIONS | Manage 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 areVIEW,DOWNLOAD,UPDATE,ADD_DISCUSSION;"share": truelets the user reshare.GETon the same path answers404when there is no share. - Not by email address:
…/collaborators/by-email-address/<email>makes anEmailcollaborator, which may onlyVIEW(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 …/collaboratorsreplaces 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
/documentsURL (200for the shared user; another user401, an anonymous visitor404), 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),
DOWNLOADcannot be shared.{"actionIds": ["DOWNLOAD", "VIEW"]}answered403, even for the administrator, since the object has noDOWNLOADaction. ShareVIEWalone: a role'sDOWNLOAD_<FIELD>grant at the company level still gives the shared user the attachment's link. A share'sUPDATElets the user PATCH the entry. - Every write notifies, an identical one too. Each
PUTsends the user a website notification, " has shared with you for viewing." (language keyx-has-shared-x-with-you-for-x), and attempts an email. So compare with theGETfirst and write only on a difference. Unlike the CMS's notifications about Space membership, these render overheadless-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, andtoUserId, and any signed in user's/o/search/v1.0/searchfinds that title and those dates (no link, no content). Leavecom.liferay.sharing.model.SharingEntryout 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
DELETEonly moves it to the Space's trash (status8, still readable by ERC); a secondDELETEremoves 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):
| Role | ERC | Who gets it |
|---|---|---|
| Asset Library Member | L_ASSET_LIBRARY_MEMBER | Members of the library or Space itself |
| Asset Library Connected Site Member | L_ASSET_LIBRARY_CONNECTED_SITE_MEMBER | Members 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
actionIdsthat 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
AccountEntryread no entry under account restriction. A regular role holdingVIEW,UPDATE, and the user actions on every account still gets404on 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
AdvancedPermissionCheckeranswerstruefor 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:GETshowed every action (update,delete,permissions,share),PATCHandDELETEworked on an entry another user owns, andPOSTanswered200withoutADD_OBJECT_ENTRY. OnlyreadOnlyfields 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |