🎯API Stability
Long-TermThis API is stable and will remain supported across versions with minimal breaking changes.

Summary

The updateRole() mutation updates a role's display name, description, display color, and permission assignments. The mutation accepts four permission categories: view permissions, organization permissions, organization management permissions, and system permissions. Each permission list replaces the current list entirely — to remove all permissions in a category, pass an empty array for that field. Because all four permission list fields are required, you must supply every category on every call, even when updating only the display name. To create a new role, use createRole().

Syntax

graphql
updateRole(
      input: UpdateRoleInput!
   ): UpdateRoleMutation!

The mutation takes a single required argument, input, of type UpdateRoleInput!. The roleId, displayName, viewPermissions, organizationPermissions, organizationManagementPermissions, and systemPermissions fields are all required. Use the roles() query to retrieve the role's identifier before calling this mutation.

The mutation returns an UpdateRoleMutation! object containing a role field that exposes the updated Role type.

Input parameters

The input argument requires the unique identifier of the role you want to update and the complete permission assignments for all four permission scopes. viewPermissions controls access to views and repositories. organizationPermissions governs organization-level capabilities. organizationManagementPermissions controls administrative operations such as managing users and groups. systemPermissions grants system-wide capabilities. All four permission list fields are required and replace the lists entirely; pass an empty array to clear all permissions in a given scope. Use the roles() query to retrieve the identifier before calling this mutation. The optional color field, introduced in version 1.282, sets the display color for the role in the UI.

Table: UpdateRoleInput Input Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
colorString  Long-Termdeprecated in 1.282The color for displaying the role.
descriptionString  Long-Term The description of the role to update.
displayNameStringyes Long-Term The display name of the role to update.
objectActionObjectAction  Long-Term The object of the action. See ObjectAction.
organizationManagementPermissionsOrganizationManagementPermissionyes Long-Term List of permissions given for organization management. See OrganizationManagementPermission.
organizationPermissionsOrganizationPermissionyes Long-Term List of permissions given for the organization. See OrganizationPermission.
roleIdStringyes Long-Term The unique identifier of the role to update.
systemPermissionsSystemPermissionyes Long-Term List of permissions given for users who are assigned the role. See SystemPermission.
viewPermissionsPermissionyes Long-Term A list of permissions associated with the view. See Permission.

Example

Raw
graphql
mutation {
  updateRole( input:
    { roleId: "abc123",
      displayName: "Testers",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  updateRole( input:
    { roleId: \"abc123\",
      displayName: \"Testers\",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  updateRole( input:
    { roleId: \"abc123\",
      displayName: \"Testers\",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  updateRole( input: ^
    { roleId: \"abc123\", ^
      displayName: \"Testers\", ^
      viewPermissions: [ ChangeDashboards, ReadAccess ] ^
    } ^
  ) ^
  { role { usersCount } } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  updateRole( input:
    { roleId: \"abc123\",
      displayName: \"Testers\",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  updateRole( input:
    { roleId: \"abc123\",
      displayName: \"Testers\",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  updateRole( input:
    { roleId: \"abc123\",
      displayName: \"Testers\",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  updateRole( input:
    { roleId: \"abc123\",
      displayName: \"Testers\",
      viewPermissions: [ ChangeDashboards, ReadAccess ]
    }
  )
  { role { usersCount } }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "updateRole": {
      "role": {
        "usersCount": 6
      }
    }
  }
}

Returned values

The mutation returns an UpdateRoleMutation! object. Its role field returns the updated Role object. You can request the role's id, displayName, description, and all four permission lists to confirm the applied changes. The usersCount and groupsCount fields report how many users and groups are currently assigned the role. Use users and groups to retrieve the full member lists. The following table lists all available fields:

Table: UpdateRoleMutation Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
roleRoleyes Long-Term The role to update. See Role.