Как изменить роль пользователя?

Насколько я вижу в api только joinGroup и leaveGroup, так что, похоже, только удалить, потом добавить.

Когда мы делаем

$user->joinGroup('Group','Role2');

MODX делает несколько запросов в базу данных.

Если упрощённо, то сначала определяет ID группы по её имени (из таблицы modx_membergroup_names), потом — ID роли (таблица modx_user_group_roles). Когда ID-шники определены, происходит создание новой записи в таблице modx_member_groups.

После этого сбрасываются значения параметров сессии:

unset($_SESSION["modx.user.{$this->get('id')}.userGroupNames"],
      $_SESSION["modx.user.{$this->get('id')}.userGroups"]);

Для удаления пользователя из группы точно так же нужно найти ID-шник группы по её имени и удалить соответствующую запись из таблицы modx_member_groups.

В итоге запись

$user->leaveGroup('Group');
$user->joinGroup('Group','Role2');

сгенерирует минимум 5 запросов к базе данных.

Если где-то ранее у нас уже определены ID-шники ролей и групп, то можно внести изменения вручную:

$group_member_arr = array(
  'member' => $user->get('id'),
  'user_group' => $group_id,
);
if (!$member = $modx->getObject('modUserGroupMember', $group_member_arr) {
  $member = $modx->newObject('modUserGroupMember', $group_member_arr);
}
$member->set('role', $role_id);
$member->save();

unset($_SESSION["modx.user.{$this->get('id')}.userGroupNames"],
      $_SESSION["modx.user.{$this->get('id')}.userGroups"]);

Но через год-полтора будет сложно понять, что тут происходит.

Так что решение о том, какой из способов выбрать, каждый принимает сам.