Custom User Roles

29/12/2025

Custom user roles enables creation of specific user roles by combining permissions in a way best matching your specific requirements.

Starting with version 10.1 you can define roles that control

which resources a user can access (server or project)
which operations a user is allowed to perform

This new approach maintains security model integrity while offering higher levels of flexibility when creating and managing custom user roles. Thereby we understand permissions, scopes and roles as described in the UMA 2.0 specifications.

You can now

create new roles
assign them to users
decide exactly which permission each role includes.

Note

Custom user roles are managed trough our REST API. The auto-generated API documentation is available in the 'Roles - roles management' section at {your_poolparty_server_base_path}/PoolParty/api).

These API endpoints enable you to list, search, create, update and delete roles as well as get a role by ID, whereby concurrency control is ensured via strong ETag reponse header and If-Match request header.

Permissions

The permission model deployed is in line with the UMA 2.0 specifications.

A permission specifies which authorization scopes are granted for a protected resource.

Resources

Resources are defined as the server resource ("Default Resource") and project resources.

The corresponding IDs are:

Default Resource: a server-wide resource;
Scopes granted here apply by default to all projects
Project resource: it is identified by a project UUID.
Project-specfic scopes can be combined with the Default Resource scopes.

Authorization Scopes

Scopes represent allowed operations on a specific resource (e.g., projects:read, projects:write). They are predefined and static.

The AuthorizationScopes tables (Server-related Scopes and Project-related Scopes) contain the available scopes and their meaning. Only authorization scopes listed in these tables are considered valid, any other values can be ignored.

This function prevents undesired concurrent changes to existing user roles. Certain endpoints provide an ETag and others require provision of the most current ETag in the request header.

The following endpoints return an ETag

GET /admin/management/roles/{id}
POST /admin/management/roles
PUT /admin/management/roles/{id}
PATCH /admin/management/roles/{id}

The following endpoints require an If_Match:

PUT /admin/management/roles/{id}
PATCH /admin/management/roles/{id}
DELETE /admin/management/roles/{id}

Error codes

428 Precondition Required: If-Match is missing
412 Precondition Failed: If-Match does not match the most current ETag

Typical workflow

Perform GET /admin/management/roles/{id} or POST /admin/management/roles
Read the ETag in the response header as you will need it for your next PUT/PATCH/DELETE request.
Perform a PUT/PATCH/DELETE request using the If-Match: <etag> header.
Note down the new ETag returned by the server as you will need it for your next call using the If-Match: <etag> header.
Use this new ETag returned by the server for your next update.
Everytime you perform a PUT/PATCH/DELETE the server will provide a new ETag in the response.

Note

Any call using an If-Match: <etag> header always requires the most recent ETag returned in the previous server response. Otherwise such a call will fail and return an error.

Tip

For more details refer to the auto-generated API documentation available at {your_poolparty_instance}/poolparty/api.

In this section: