Roles and authorities
How permissions work, and how to list roles and grant or revoke their authorities.
BPMS uses the permission model of BPMS 3.x, so every existing role keeps its access. A user's permissions come from the user's roles, and each role holds a list of authority codes: the codes of the BPMS 3.x menu, such as 6.2.1.4 (view roles).
How authorities are checked
- Each operation requires an authority code. The caller holds it when one of the caller's roles in the caller's tenant stores that code or a more specific one: a role with
5.3.8also holds5.3and5, as in BPMS 3.x. - A parent code never grants its children: a role with
5.3does not hold5.3.8. - Without the authority, the call answers
403with the codecore.authority-required, and the refusal is recorded in the audit log with the user, the tenant, the action, and the request id.
List the roles
curl -sS -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles?page=0&size=20&sort=name"It requires the view-roles authority, 6.2.1.4, and lists only the roles of your tenant, without deleted ones. First call describes its parameters and answer.
Grant an authority
curl -sS -X PUT -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles/<roleId>/authorities/<code>"It adds the code to the role and answers 204, also when the role already holds it. It requires the edit-roles authority, 6.2.1.2, and the code being granted: a user can only grant authorities the user holds.
Revoke an authority
curl -sS -X DELETE -H "Authorization: Bearer $TOKEN" "$BPMS_URL/api/v1/access/roles/<roleId>/authorities/<code>"It removes exactly that code from the role and answers 204, also when the role did not hold it. Revoking 5.3 keeps 5.3.8. It requires the edit-roles authority, 6.2.1.2. A role always keeps at least one authority.
Every grant and revocation is recorded in the audit log in the same transaction as the change, so a change without its record cannot happen.
Errors
| Status | code | When |
|---|---|---|
400 | core.validation-failed | The code is not a BPMS 3.x authority code, or a list parameter is invalid. |
401 | core.authentication-required | The call has no valid token. |
403 | core.authority-required | The caller lacks the authority the operation requires. |
404 | access.role-not-found | The role does not exist in your tenant or is deleted. |
409 | access.role-authority-required | The revocation would leave the role without authorities. |
In the OpenAPI document, the operations are listRoles, grantRoleAuthority, and revokeRoleAuthority, under the access tag.