Custom User Roles - Workflows

API validation prevents the creation of roles with spaces or special characters. If roles are created or edited via Keycloak, administrators must manually ensure compliance with naming conventions to prevent 'Unexpected Character' errors in the Graph Modeling interface.

The name parameter must be provided.
The name parameter must match the regex ^[a-zA-Z]{2}[a-zA-Z0-9_-]{1,50}$:
- Starts with: At least two letters (A-Z, a-z)
- Following characters: 1–50 characters consisting of letters, digits, underscores (_), or hyphens (-).
- Total Length: Minimum 3 characters, maximum 52 characters.
No special characters (except for _ and -) are allowed.
Must be relevant: Some names may be forbidden by system configuration.
Uniqueness: The name must be unique and not already exist in the system.
Reserved Names: You cannot use reserved system role names for custom roles.

Valid Role Name Examples	Invalid Role Name Examples
`Abc`	`a` (Too short)
`AdminRole_1`	`1Admin` (Must start with two letters)
`My-Role`	`MyRole` (Illegal character ``)

Endpoint: GET admin/management/roles

Parameter	Details
`page`	optional, default 1; page number (starting at 1)
`size`	optional, default 10; page size
`q`	optional; free-text search by role attributes
`system`	optional, boolean; by default no filtering is applied; if set to `true` then only the default/system roles will be returned; if set to `false` then only custom roles are returned;
`permission`	optional, repeatable; filtering by required permission(s) Example: `?permission=projects:read&permission=ontologies:read`
`sort`	optional; sorting by field; prefix with `-` for descending Example: `sort=name` (ascending) or `sort=-name` (descending) when sorting by permissions then the flat number of scopes is used for comparison; flat number means that when a certain operation is granted to multiple resources, then it is only counted once; for instance we have two resources with two scopes assigned for the first one, and three scopes to the other; one scope is however assigned to both resources, the returned number of scopes is four.
	Example of how sorting by permissions works "permissions" : { "resourceId1": ["projects:read", "projects:write"], "resourceId2": ["projects:read", "ontologies:read", "ontologies:write"] } The example above shows a total of five scopes; but the response only lists four as `projects:read` only counts once: ["projects:read", "projects:write", "ontologies:read", "ontologies:write"]

{
    "items": [
        {
            "id": "71e72ed3-cff5-40c3-8cb0-5cc9ad878e1a",
            "name": "PoolPartyAdmin",
            "displayName": "useradmin.role.PoolPartyAdmin",
            "description": "System role: PoolPartyAdmin",
            "permissions": {
                "Default Resource": [
                    "classifiers:create",
                    "corpora:delete",
                    "ontologies:read",
                    "project-notifications",
                    "opendata",
                    "projects:create",
                    "quality-settings",
                    "project-events:delete",
                    "ontologies:delete",
                    "corpora:read",
                    "corpora:write",
                    "login",
                    "projects:delete",
                    "classifiers:read",
                    "workflows:assign",
                    "apis:read",
                    "wiki:read",
                    "workflows:update",
                    "ontologies:write",
                    "projects:read",
                    "dashboard",
                    "workflows:configure",
                    "inscheme",
                    "concepts:change-uri",
                    "skosxl",
                    "projects:write",
                    "project.groups",
                    "projects:advanced-configure",
                    "project-customschema",
                    "projects:sparql-update",
                    "classifiers:write",
                    "projects:link",
                    "corpora:create",
                    "projects:publish",
                    "collaboration",
                    "ontologies:create",
                    "apis:write",
                    "classifiers:delete",
                    "snapshots:write",
                    "advanced-uri-settings"
                ]
            },
            "system": true,
            "createdAt": "2025-10-27T11:17:11.618546712Z",
            "updatedAt": "2025-11-03T14:52:06.305783279Z"
        },
        {
            "id": "4e83b3bb-79fd-45a3-bf62-c40b86baf888",
            "name": "PoolPartySuperAdmin",
            "displayName": "useradmin.role.PoolPartySuperAdmin",
            "description": "System role: PoolPartySuperAdmin",
            "permissions": {
                "Default Resource": [
                    "corpora:delete",
                    "classifiers:create",
                    "triples:delete",
                    "projects:create",
                    "opendata",
                    "users:read",
                    "quality-settings",
                    "ontologies:delete",
                    "remote-systems.metadata",
                    "remote-systems",
                    "admin:scripts",
                    "users:write",
                    "projects:read",
                    "dashboard",
                    "inscheme",
                    "projects:sparql-update",
                    "corpora:create",
                    "classifiers:write",
                    "project.users:write",
                    "users:create",
                    "classifiers:delete",
                    "ontologies:read",
                    "project-notifications",
                    "project-events:delete",
                    "users:delete",
                    "corpora:read",
                    "login",
                    "corpora:write",
                    "projects:delete",
                    "classifiers:read",
                    "workflows:assign",
                    "apis:read",
                    "wiki:read",
                    "workflows:update",
                    "admin.dashboard",
                    "ontologies:write",
                    "workflows:configure",
                    "concepts:change-uri",
                    "projects:write",
                    "skosxl",
                    "corpus-language-model-settings",
                    "project.groups",
                    "projects:advanced-configure",
                    "project-customschema",
                    "projects:link",
                    "projects:publish",
                    "collaboration",
                    "ontologies:create",
                    "migration",
                    "apis:write",
                    "snapshots:write",
                    "advanced-uri-settings"
                ]
            },
            "system": true,
            "createdAt": "2025-10-27T11:17:08.551234176Z",
            "updatedAt": "2025-11-03T14:52:06.275097010Z"
        },
        {
            "id": "db74a1e5-6acc-404f-ac77-51f50202bda1",
            "name": "ApiAdmin",
            "displayName": "useradmin.role.ApiAdmin",
            "description": "System role: ApiAdmin",
            "permissions": {
                "Default Resource": [
                    "classifiers:create",
                    "corpora:delete",
                    "ontologies:read",
                    "project-notifications",
                    "opendata",
                    "projects:create",
                    "quality-settings",
                    "project-events:delete",
                    "ontologies:delete",
                    "corpora:read",
                    "corpora:write",
                    "projects:delete",
                    "classifiers:read",
                    "workflows:assign",
                    "apis:read",
                    "wiki:read",
                    "workflows:update",
                    "ontologies:write",
                    "projects:read",
                    "dashboard",
                    "workflows:configure",
                    "inscheme",
                    "concepts:change-uri",
                    "skosxl",
                    "projects:write",
                    "project.groups",
                    "projects:advanced-configure",
                    "project-customschema",
                    "projects:sparql-update",
                    "classifiers:write",
                    "projects:link",
                    "corpora:create",
                    "projects:publish",
                    "collaboration",
                    "ontologies:create",
                    "apis:write",
                    "classifiers:delete",
                    "snapshots:write",
                    "advanced-uri-settings"
                ]
            },
            "system": true,
            "createdAt": "2025-10-27T11:17:04.905936044Z",
            "updatedAt": "2025-11-03T14:52:06.237820161Z"
        }
    ],
    "page": 1,
    "pageCount": 1,
    "totalCount": 3
}

Endpoint: GET /admin/management/roles/{id}

Returns success code 200 with a JSON body and an ETag header on success
Returns error code 404 if the role does not exist

In the response find the ETag header (e.g. ETag: "qcFiJRhhwpeeSD3xFW69qLU1LckJVfZbJNso4goEzYY")

{
    "id": "71e72ed3-cff5-40c3-8cb0-5cc9ad878e1a",
    "name": "PoolPartyAdmin",
    "displayName": "useradmin.role.PoolPartyAdmin",
    "description": "System role: PoolPartyAdmin",
    "permissions": {
        "Default Resource": [
            "classifiers:create",
            "corpora:delete",
            "ontologies:read",
            "project-notifications",
            "opendata",
            "projects:create",
            "quality-settings",
            "project-events:delete",
            "ontologies:delete",
            "corpora:read",
            "corpora:write",
            "login",
            "projects:delete",
            "classifiers:read",
            "workflows:assign",
            "apis:read",
            "wiki:read",
            "workflows:update",
            "ontologies:write",
            "projects:read",
            "dashboard",
            "workflows:configure",
            "inscheme",
            "concepts:change-uri",
            "skosxl",
            "projects:write",
            "project.groups",
            "projects:advanced-configure",
            "project-customschema",
            "projects:sparql-update",
            "classifiers:write",
            "projects:link",
            "corpora:create",
            "projects:publish",
            "collaboration",
            "ontologies:create",
            "apis:write",
            "classifiers:delete",
            "snapshots:write",
            "advanced-uri-settings"
        ]
    },
    "system": true,
    "createdAt": "2025-10-27T11:17:11.618546712Z",
    "updatedAt": "2025-11-03T14:52:06.305783279Z"
}

Endpoint: POST /admin/management/roles

Field	Details
`name`	mandatory
`displayName`	optional
`description`	optional
`permissions`	optional; a map of a resouce, i.e. a set of permissions

Returns: success code 201

Created with Location: /admin/management/roles/{id} and ETag

{
  "name": "TMP_NEW_TEST",
  "displayName": "TMP role new",
  "description": "New role to test new mapping",
  "permissions": {
    "Default Resource": [
      "apis:read",
      "projects:read",
      "projects:view",
      "projects:publish",
      "projects:link",
      "projects:advanced-configure",
      "project.groups",
      "project-notifications"
    ],
    "ccc7dc19-1711-43e7-8eab-395b68276127": [
      "apis:read",
      "projects:read",
      "projects:view",
      "projects:publish",
      "projects:link",
      "projects:advanced-configure",
      "project.groups",
      "project-notifications"
    ]
  }
}

Location: /admin/management/roles/da7dc8fa-3de3-4123-877c-c43feba7382e

{
    "id": "da7dc8fa-3de3-4123-877c-c43feba7382e",
    "name": "TMP_NEW_TEST",
    "displayName": "TMP role new",
    "description": "New role to test new mapping",
    "permissions": {
        "Default Resource": [
            "projects:link",
            "apis:read",
            "projects:publish",
            "project-notifications",
            "project.groups",
            "projects:view",
            "projects:read",
            "projects:advanced-configure"
        ],
        "ccc7dc19-1711-43e7-8eab-395b68276127": [
            "projects:link",
            "apis:read",
            "projects:publish",
            "project-notifications",
            "project.groups",
            "projects:view",
            "projects:read",
            "projects:advanced-configure"
        ]
    },
    "system": false,
    "createdAt": "2025-11-11T07:50:17.960100563Z",
    "updatedAt": "2025-11-11T07:50:17.960100563Z"
}

Endpoint: PUT /admin/management/roles/{id}

Requires: If-Match header (value must be the latest ETag for the role)

Body: full representation; skipped fields will be treated as null/empty and may clear data

Important

If the permissions array is skipped, it will be replaced with an empty map (clearing permissions).

Errors

error code 404 Not Found if the role does not exist
error code 428 Precondition Required if If-Match is missing
error code 412 Precondition Failed if If-Match does not match current ETag

Returns: success code 200 with updated body and a new ETag

{
    "id": "da7dc8fa-3de3-4123-877c-c43feba7382e",
    "name": "TMP_NEW_TEST_changed",
    "displayName": "displayname changed",
    "description": "description changed",
    "permissions": {
        "Default Resource": [
            "wiki:read",
            "corpora:read"
        ],
        "ccc7dc19-1711-43e7-8eab-395b68276127": [
            "projects:link",
            "apis:read",
            "projects:publish",
            "project-notifications",
            "project.groups",
            "projects:view",
            "projects:read",
            "projects:advanced-configure"
        ]
    },
    "system": false,
    "createdAt": "2025-11-11T07:50:17.960100563Z",
    "updatedAt": "2025-11-11T07:57:11.488244699Z"
}

Endpoint: PATCH /roles/{id}

Requires: If-Match header

Format: application/json and additionally application/merge-patch+json

Body: only the fields you want to change;partial RoleUpdate; omitted fields remain unchanged

Returns: success code 200 with updated body and a new ETag

Errors:

error code 404 Not Found if the role does not exist
error code 428 Precondition Required if If-Match is missing
error code 412 Precondition Failed if If-Match does not match current ETag

{
    "id": "da7dc8fa-3de3-4123-877c-c43feba7382e",
    "name": "TMP_NEW_TEST_changed",
    "displayName": "displayname changed",
    "description": "Partially updated description",
    "permissions": {
        "Default Resource": [
            "wiki:read",
            "corpora:read"
        ],
        "ccc7dc19-1711-43e7-8eab-395b68276127": [
            "projects:link",
            "apis:read",
            "projects:publish",
            "project-notifications",
            "project.groups",
            "projects:view",
            "projects:read",
            "projects:advanced-configure"
        ]
    },
    "system": false,
    "createdAt": "2025-11-11T07:50:17.960100563Z",
    "updatedAt": "2025-11-11T08:16:28.048207539Z"
}

Endpoint: DELETE /admin/management/roles/{id}

Requires: If-Match header with the latest ETag for the role

Returns: success code 204; No Content on success

Errors:

error code 404 Not Found if the role does not exist
error code 428 Precondition Required if If-Match is missing
error code 412 Precondition Failed if If-Match does not match current ETag

Always GET the role or use the ETag from the last successful POST/PUT/PATCH before attempting a mutating request. Use this ETag in If-Match.
After a successful PUT/PATCH, update the stored ETag with the value from the response; you need the latest ETag for the next change or deletion.
Preferably use PATCH for small changes to avoid unintentionally clearing of skipped fields (like permissions). Use PUT when you intend to fully replace the resource.
For sorting, prefix the field with - for descending order (e.g., sort=-name).
For permission-based filtering, repeat the permission parameter for multiple required permissions.