Create and manage custom roles

Console

1. In the Google Cloud console, go to the Rolespage.

   Go to the Roles page

2. Using the drop-down list at the top of the page, select the project or organization that contains the role that you want to edit.

3. Click a custom role.

4. Click Edit Role.

5. To update the role's metadata, edit the role's Title, Description, or Role launch stage.

6. To update the role's permissions, do the following:

   1. Click Add Permissionsto add new permissions to the role.
   2. Uncheck permissions to remove permissions from the role.

7. Click Updateto save the edited role.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use the gcloud iam roles update command to update custom roles. You can use this command in two ways:

   • By providing a YAML file that contains the updated role definition

   • By using flags to specify the updated role definition

   When updating a custom role, you must specify whether it applies to the organization level or project level by using the --organization= ORGANIZATION_ID or --project= PROJECT_ID flags. Each example below creates a custom role at the project level.

   To update a custom role using a YAML file:

   Get the current definition for the role by executing one of the following commands:

   • To get the role definition of an organization-level custom role, execute the following command:

     gcloud iam roles describe ROLE_ID 
     --organization= ORGANIZATION_ID 
     

   • To get the role definition of a project-level custom role, execute the following command:

     gcloud iam roles describe ROLE_ID 
     --project= PROJECT_ID 
     

   Each placeholder value is described below:

   • ROLE_ID is the name of the role to update, such as myCompanyAdmin .

   • ORGANIZATION_ID is the numeric ID of the organization, such as 123456789012 .

   • PROJECT_ID is the name of the project, such as my-project .

   The describe command returns the role's definition and includes an etag value that uniquely identifies the current version of the role. The etag value should be provided in the updated role definition to ensure that any concurrent role changes are not overwritten.

   The describe command returns the following output:

    description 
    : 
     
     ROLE_DESCRIPTION 
    
    etag 
    : 
     
     ETAG 
    
    includedPermissions 
    : 
    - 
     
     PERMISSION_1 
    
    - 
     
     PERMISSION_2 
    
    name 
    : 
     
     ROLE_NAME 
    
    stage 
    : 
     
     LAUNCH_STAGE 
    
    title 
    : 
     
     ROLE_TITLE 
    
   

   Each placeholder value is described below:

   • ROLE_DESCRIPTION is a short description of the role, such as "My custom role description" .

   • ETAG is the unique identifier for the current version of the role, such as BwVkBkbfr70= .

   • PERMISSION_1 and PERMISSION_2 are permissions to include in the custom role, such as iam.roles.get . You can't use wildcard characters ( * ) in permission names.

   • ROLE_NAME is the full role name, including any organizations/ , projects/ , or roles/ prefixes. For example, organizations/123456789012/roles/myCompanyAdmin.

   • LAUNCH_STAGE indicates the stage of a role in the launch lifecycle, such as ALPHA , BETA , or GA .

   • ROLE_TITLE is a friendly title for the role, such as "My Company Admin" .

   To update the role, either include the outputted role definition to a YAML file or update the original YAML file with the outputted etag value.

   Consider the following example YAML file, which contains the output from the describe command for a project-level role and adds two Cloud Storage permissions:

    description 
    : 
     
    My custom role description. 
    etag 
    : 
     
    BwVkBkbfr70= 
    includedPermissions 
    : 
    - 
     
    iam.roles.get 
    - 
     
    iam.roles.list 
    - 
     
    storage.buckets.get 
    - 
     
    storage.buckets.list 
    name 
    : 
     
    projects/my-project/roles/myCompanyAdmin 
    stage 
    : 
     
    ALPHA 
    title 
    : 
     
    My Company Admin 
   

   Save the YAML file, and then execute one of the following commands:

   • To update an organization-level role, execute the following command:

     gcloud iam roles update ROLE_ID 
     --organization= ORGANIZATION_ID 
     \
         --file= YAML_FILE_PATH 
     

   • To update a project-level role, execute the following command:

     gcloud iam roles update ROLE_ID 
     --project= PROJECT_ID 
     \
         --file= YAML_FILE_PATH 
     

   Each placeholder value is described below:

   • ROLE_ID is the name of the role to update, such as myCompanyAdmin .

   • ORGANIZATION_ID is the numeric ID of the organization, such as 123456789012 .

   • PROJECT_ID is the name of the project, such as my-project-id .

   • YAML_FILE_PATH is the path to the location of your YAML file that contains the updated custom role definition.

   Examples

   The following example demonstrates how to update an organization-level role using a YAML file:

   gcloud iam roles update ROLE_ID 
   --organization= ORGANIZATION_ID 
   \
       --file= YAML_FILE_PATH 
   

   • To update a project-level role, execute the following command:

     gcloud iam roles update ROLE_ID 
     --project= PROJECT_ID 
     \
         --file= YAML_FILE_PATH 
     

   Each placeholder value is described below:

   • ROLE_ID is the name of the role to update, such as myCompanyAdmin .

   • ORGANIZATION_ID is the numeric ID of the organization, such as 123456789012 .

   • PROJECT_ID is the name of the project, such as my-project .

   • YAML_FILE_PATH is the path to the location of your YAML file that contains the updated custom role definition.

   Examples

   The following example demonstrates how to update an organization-level role using a YAML file:

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --file=my-role-definition.yaml

   If the role was updated successfully, the command's output is similar to the following:

    description 
    : 
     
    My custom role description. 
    etag 
    : 
     
    BwVkBwDN0lg= 
    includedPermissions 
    : 
    - 
     
    iam.roles.get 
    - 
     
    iam.roles.list 
    - 
     
    storage.buckets.get 
    - 
     
    storage.buckets.list 
    name 
    : 
     
    organizations/123456789012/roles/myCompanyAdmin 
    stage 
    : 
     
    ALPHA 
    title 
    : 
     
    My Company Admin 
   

   The following example demonstrates how to update a project-level role using a YAML file:

   gcloud iam roles update myCompanyAdmin --project=my-project \
       --file=my-role-definition.yaml

   If the role was updated successfully, the command's output is similar to the following:

    description 
    : 
     
    My custom role description. 
    etag 
    : 
     
    BwVkBwDN0lg= 
    includedPermissions 
    : 
    - 
     
    iam.roles.get 
    - 
     
    iam.roles.list 
    - 
     
    storage.buckets.get 
    - 
     
    storage.buckets.list 
    name 
    : 
     
    projects/my-project/roles/myCompanyAdmin 
    stage 
    : 
     
    ALPHA 
    title 
    : 
     
    My Company Admin 
   

   To update a custom role using flags:

   Each part of a role definition can be updated using a corresponding flag. See the gcloud iam roles update topic for a list of all possible flags.

   You can use the following flags to add or remove permissions:

   • --add-permissions= PERMISSIONS : Adds one or more comma-separated permissions to the role. You can't use wildcard characters ( * ) in permission names.

   • --remove-permissions= PERMISSIONS : Removes one or more comma-separated permissions from the role. You can't use wildcard characters ( * ) in permission names.

   Alternatively, you can simply specify the new permissions using the --permissions= PERMISSIONS flag and providing a comma-separated list of permissions to replace the existing permissions list.

   To update other parts of the role definition, execute one of the following commands:

   • To update an organization-level role, execute the following command:

     gcloud iam roles update ROLE_ID 
     --organization= ORGANIZATION_ID 
     \
         --title= ROLE_TITLE 
     --description= ROLE_DESCRIPTION 
     \
         --stage= LAUNCH_STAGE 
     

   • To update a project-level role, execute the following command:

     gcloud iam roles update ROLE_ID 
     --project= PROJECT_ID 
     \
         --title= ROLE_TITLE 
     --description= ROLE_DESCRIPTION 
     \
         --stage= LAUNCH_STAGE 
     

   Each placeholder value is described below:

   • ROLE_ID is the name of the role, such as myCompanyAdmin .

   • ORGANIZATION_ID is the numeric ID of the organization, such as 123456789012 .

   • PROJECT_ID is the name of the project, such as my-project .

   • ROLE_TITLE is a friendly title for the role, such as "My Company Admin" .

   • ROLE_DESCRIPTION is a short description of the role, such as "My custom role description." .

   • LAUNCH_STAGE indicates the stage of a role in the launch lifecycle, such as ALPHA , BETA , or GA .

   Examples

   The following example demonstrates how to add permissions to an organization-level role using flags:

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \
       --add-permissions="storage.buckets.get,storage.buckets.list"

   If the role was updated successfully, the command's output is similar to the following:

    description 
    : 
     
    My custom role description. 
    etag 
    : 
     
    BwVkBwDN0lg= 
    includedPermissions 
    : 
    - 
     
    iam.roles.get 
    - 
     
    iam.roles.list 
    - 
     
    storage.buckets.get 
    - 
     
    storage.buckets.list 
    name 
    : 
     
    organizations/123456789012/roles/myCompanyAdmin 
    stage 
    : 
     
    ALPHA 
    title 
    : 
     
    My Company Admin 
   

   The following example demonstrates how to add permissions to a project-level role using flags:

   gcloud iam roles update myCompanyAdmin --project=my-project \
       --add-permissions="storage.buckets.get,storage.buckets.list"

   If the role was updated successfully, the command's output is similar to the following:

    description 
    : 
     
    My custom role description. 
    etag 
    : 
     
    BwVkBwDN0lg= 
    includedPermissions 
    : 
    - 
     
    iam.roles.get 
    - 
     
    iam.roles.list 
    - 
     
    storage.buckets.get 
    - 
     
    storage.buckets.list 
    name 
    : 
     
    projects/my-project/roles/myCompanyAdmin 
    stage 
    : 
     
    ALPHA 
    title 
    : 
     
    My Company Admin 
   

C++

To learn how to install and use the client library for IAM, see IAM client libraries . For more information, see the IAM C++ API reference documentation .

To authenticate to IAM, set up Application Default Credentials. For more information, see Before you begin .

  namespace 
  
 iam 
  
 = 
  
 :: 
 google 
 :: 
 cloud 
 :: 
 iam_admin_v1 
 ; 
 []( 
 std 
 :: 
 string 
  
 const 
&  
 name 
 , 
  
 std 
 :: 
 string 
  
 const 
&  
 title 
 ) 
  
 { 
  
 iam 
 :: 
 IAMClient 
  
 client 
 ( 
 iam 
 :: 
 MakeIAMConnection 
 ()); 
  
 google 
 :: 
 iam 
 :: 
 admin 
 :: 
 v1 
 :: 
 UpdateRoleRequest 
  
 request 
 ; 
  
 request 
 . 
 set_name 
 ( 
 name 
 ); 
  
 google 
 :: 
 iam 
 :: 
 admin 
 :: 
 v1 
 :: 
 Role 
  
 role 
 ; 
  
 role 
 . 
 set_title 
 ( 
 title 
 ); 
  
 google 
 :: 
 protobuf 
 :: 
 FieldMask 
  
 update_mask 
 ; 
  
 * 
 update_mask 
 . 
 add_paths 
 () 
  
 = 
  
 "title" 
 ; 
  
 * 
 request 
 . 
 mutable_role 
 () 
  
 = 
  
 role 
 ; 
  
 * 
 request 
 . 
 mutable_update_mask 
 () 
  
 = 
  
 update_mask 
 ; 
  
 auto 
  
 response 
  
 = 
  
 client 
 . 
 UpdateRole 
 ( 
 request 
 ); 
  
 if 
  
 ( 
 ! 
 response 
 ) 
  
 throw 
  
 std 
 :: 
 move 
 ( 
 response 
 ). 
 status 
 (); 
  
 std 
 :: 
 cout 
 << 
 "Role successfully updated: " 
 << 
 response 
 - 
> DebugString 
 () 
 << 
 " 
 \n 
 " 
 ; 
 } 
 

C#

To learn how to install and use the client library for IAM, see IAM client libraries . For more information, see the IAM C# API reference documentation .

To authenticate to IAM, set up Application Default Credentials. For more information, see Before you begin .

  using 
  
 System 
 ; 
 using 
  
 System.Collections.Generic 
 ; 
 using 
  
  Google.Apis.Auth.OAuth2 
 
 ; 
 using 
  
 Google.Apis.Iam.v1 
 ; 
 using 
  
 Google.Apis.Iam.v1.Data 
 ; 
 public 
  
 partial 
  
 class 
  
 CustomRoles 
 { 
  
 public 
  
 static 
  
 Role 
  
 EditRole 
 ( 
 string 
  
 name 
 , 
  
 string 
  
 projectId 
 , 
  
 string 
  
 newTitle 
 , 
  
 string 
  
 newDescription 
 , 
  
 IList<string> 
  
 newPermissions 
 , 
  
 string 
  
 newStage 
 ) 
  
 { 
  
 var 
  
 credential 
  
 = 
  
  GoogleCredential 
 
 . 
  GetApplicationDefault 
 
 () 
  
 . 
  CreateScoped 
 
 ( 
 IamService 
 . 
 Scope 
 . 
 CloudPlatform 
 ); 
  
 var 
  
 service 
  
 = 
  
 new 
  
 IamService 
 ( 
 new 
  
 IamService 
 . 
 Initializer 
  
 { 
  
 HttpClientInitializer 
  
 = 
  
 credential 
  
 }); 
  
 // First, get a Role using List() or Get(). 
  
 string 
  
 resource 
  
 = 
  
 $"projects/{projectId}/roles/{name}" 
 ; 
  
 var 
  
 role 
  
 = 
  
 service 
 . 
 Projects 
 . 
 Roles 
 . 
 Get 
 ( 
 resource 
 ). 
 Execute 
 (); 
  
 // Then you can update its fields. 
  
 role 
 . 
 Title 
  
 = 
  
 newTitle 
 ; 
  
 role 
 . 
 Description 
  
 = 
  
 newDescription 
 ; 
  
 role 
 . 
 IncludedPermissions 
  
 = 
  
 newPermissions 
 ; 
  
 role 
 . 
 Stage 
  
 = 
  
 newStage 
 ; 
  
 role 
  
 = 
  
 service 
 . 
 Projects 
 . 
 Roles 
 . 
 Patch 
 ( 
 role 
 , 
  
 resource 
 ). 
 Execute 
 (); 
  
 Console 
 . 
 WriteLine 
 ( 
 "Updated role: " 
  
 + 
  
 role 
 . 
 Name 
 ); 
  
 return 
  
 role 
 ; 
  
 } 
 } 
 

Go

To learn how to install and use the client library for IAM, see IAM client libraries . For more information, see the IAM Go API reference documentation .

To authenticate to IAM, set up Application Default Credentials. For more information, see Before you begin .

  import 
  
 ( 
  
 "context" 
  
 "fmt" 
  
 "io" 
  
 iam 
  
 "google.golang.org/api/iam/v1" 
 ) 
 // editRole modifies a custom role. 
 func 
  
 editRole 
 ( 
 w 
  
 io 
 . 
 Writer 
 , 
  
 projectID 
 , 
  
 name 
 , 
  
 newTitle 
 , 
  
 newDescription 
 , 
  
 newStage 
  
 string 
 , 
  
 newPermissions 
  
 [] 
 string 
 ) 
  
 ( 
 * 
 iam 
 . 
 Role 
 , 
  
 error 
 ) 
  
 { 
  
 ctx 
  
 := 
  
 context 
 . 
 Background 
 () 
  
 service 
 , 
  
 err 
  
 := 
  
 iam 
 . 
 NewService 
 ( 
 ctx 
 ) 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "iam.NewService: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 resource 
  
 := 
  
 "projects/" 
  
 + 
  
 projectID 
  
 + 
  
 "/roles/" 
  
 + 
  
 name 
  
 role 
 , 
  
 err 
  
 := 
  
 service 
 . 
 Projects 
 . 
 Roles 
 . 
 Get 
 ( 
 resource 
 ). 
 Do 
 () 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "Projects.Roles.Get: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 role 
 . 
 Title 
  
 = 
  
 newTitle 
  
 role 
 . 
 Description 
  
 = 
  
 newDescription 
  
 role 
 . 
 IncludedPermissions 
  
 = 
  
 newPermissions 
  
 role 
 . 
 Stage 
  
 = 
  
 newStage 
  
 role 
 , 
  
 err 
  
 = 
  
 service 
 . 
 Projects 
 . 
 Roles 
 . 
 Patch 
 ( 
 resource 
 , 
  
 role 
 ). 
 Do 
 () 
  
 if 
  
 err 
  
 != 
  
 nil 
  
 { 
  
 return 
  
 nil 
 , 
  
 fmt 
 . 
 Errorf 
 ( 
 "Projects.Roles.Patch: %w" 
 , 
  
 err 
 ) 
  
 } 
  
 fmt 
 . 
 Fprintf 
 ( 
 w 
 , 
  
 "Updated role: %v" 
 , 
  
 role 
 . 
 Name 
 ) 
  
 return 
  
 role 
 , 
  
 nil 
 } 
 

Java

To learn how to install and use the client library for IAM, see IAM client libraries . For more information, see the IAM Java API reference documentation .

To authenticate to IAM, set up Application Default Credentials. For more information, see Before you begin .

  import 
  
 com.google.cloud.iam.admin.v1. IAMClient 
 
 ; 
 import 
  
 com.google.iam.admin.v1. Role 
 
 ; 
 import 
  
 com.google.iam.admin.v1. Role 
. RoleLaunchStage 
 
 ; 
 import 
  
 com.google.iam.admin.v1. UpdateRoleRequest 
 
 ; 
 import 
  
 com.google.protobuf. FieldMask 
 
 ; 
 import 
  
 java.io.IOException 
 ; 
 /** Edit role metadata. Specifically, update description and launch stage. */ 
 public 
  
 class 
 EditRole 
  
 { 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 // TODO(developer): Replace the variables before running the sample. 
  
 // Role ID must point to an existing role. 
  
 String 
  
 projectId 
  
 = 
  
 "your-project-id" 
 ; 
  
 String 
  
 roleId 
  
 = 
  
 "a unique identifier (e.g. testViewer)" 
 ; 
  
 String 
  
 description 
  
 = 
  
 "a new description of the role" 
 ; 
  
 editRole 
 ( 
 projectId 
 , 
  
 roleId 
 , 
  
 description 
 ); 
  
 } 
  
 public 
  
 static 
  
 void 
  
 editRole 
 ( 
 String 
  
 projectId 
 , 
  
 String 
  
 roleId 
 , 
  
 String 
  
 description 
 ) 
  
 throws 
  
 IOException 
  
 { 
  
 String 
  
 roleName 
  
 = 
  
 "projects/" 
  
 + 
  
 projectId 
  
 + 
  
 "/roles/" 
  
 + 
  
 roleId 
 ; 
  
  Role 
 
 . 
 Builder 
  
 roleBuilder 
  
 = 
  
  Role 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 roleName 
 ) 
  
 . 
 setDescription 
 ( 
 description 
 ) 
  
 // See launch stage enums at 
  
 // https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage 
  
 . 
 setStage 
 ( 
  RoleLaunchStage 
 
 . 
 GA 
 ); 
  
  FieldMask 
 
  
 fieldMask 
  
 = 
  
  FieldMask 
 
 . 
 newBuilder 
 (). 
  addPaths 
 
 ( 
 "description" 
 ). 
  addPaths 
 
 ( 
 "stage" 
 ). 
 build 
 (); 
  
  UpdateRoleRequest 
 
  
 updateRoleRequest 
  
 = 
  
  UpdateRoleRequest 
 
 . 
 newBuilder 
 () 
  
 . 
 setName 
 ( 
 roleName 
 ) 
  
 . 
 setRole 
 ( 
 roleBuilder 
 ) 
  
 . 
 setUpdateMask 
 ( 
 fieldMask 
 ) 
  
 . 
 build 
 (); 
  
 // Initialize client for sending requests. This client only needs to be created 
  
 // once, and can be reused for multiple requests. 
  
 try 
  
 ( 
  IAMClient 
 
  
 iamClient 
  
 = 
  
  IAMClient 
 
 . 
 create 
 ()) 
  
 { 
  
  Role 
 
  
 result 
  
 = 
  
 iamClient 
 . 
 updateRole 
 ( 
 updateRoleRequest 
 ); 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 "Edited role:\n" 
  
 + 
  
 result 
 ); 
  
 } 
  
 } 
 } 
 

Python

To learn how to install and use the client library for IAM, see IAM client libraries . For more information, see the IAM Python API reference documentation .

To authenticate to IAM, set up Application Default Credentials. For more information, see Before you begin .

  from 
  
 google.api_core.exceptions 
  
 import 
 NotFound 
 from 
  
 google.cloud.iam_admin_v1 
  
 import 
  IAMClient 
 
 , 
  Role 
 
 , 
  UpdateRoleRequest 
 
 from 
  
 snippets.get_role 
  
 import 
 get_role 
 def 
  
 edit_role 
 ( 
 role 
 : 
 Role 
 ) 
 - 
> Role 
 : 
  
 """Edits an existing IAM role in a GCP project. 
 Args: 
 role: google.cloud.iam_admin_v1.Role object to be updated 
 Returns: Updated google.cloud.iam_admin_v1.Role object 
 """ 
 client 
 = 
 IAMClient 
 () 
 request 
 = 
 UpdateRoleRequest 
 ( 
 name 
 = 
 role 
 . 
 name 
 , 
 role 
 = 
 role 
 ) 
 try 
 : 
 role 
 = 
 client 
 . 
  update_role 
 
 ( 
 request 
 ) 
 print 
 ( 
 f 
 "Edited role: 
 { 
 role 
 . 
 name 
 } 
 : 
 { 
 role 
 } 
 " 
 ) 
 return 
 role 
 except 
 NotFound 
 : 
 print 
 ( 
 f 
 "Role [ 
 { 
 role 
 . 
 name 
 } 
 ] not found, take some actions" 
 ) 
 

REST

The roles.patch method updates a custom role in a project or organization.

Before using any of the request data, make the following replacements:

Required:

• RESOURCE_TYPE : The resource type whose custom roles you want to manage. Use the value projects or organizations .
• RESOURCE_ID : The project ID or organization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, like my-project . Organization IDs are numeric, like 123456789012 .
• ROLE_NAME : The full role name, including any organizations/ , projects/ , or roles/ prefixes. For example, organizations/123456789012/roles/myCompanyAdmin .

Recommended:

• ETAG : An identifier for a version of the role. Include this field to prevent overwriting other role changes.

Optional (define one or more of the following values):

• ROLE_TITLE : The human-readable title for the role. For example, My Company Admin .
• ROLE_DESCRIPTION : A description for the role. For example, "The company admin role allows company admins to access important resources" .
• PERMISSION_1 and PERMISSION_2 : The permissions that you want to include in the role. For example, storage.objects.update . You can't use wildcard characters ( * ) in permission names.
• LAUNCH_STAGE : The current launch stage of the role. This field can contain one of the following values: EAP , ALPHA , BETA , GA , DEPRECATED , or DISABLED .

HTTP method and URL:

PATCH https://iam.googleapis.com/v1/ RESOURCE_TYPE 
/ RESOURCE_ID 
/roles

Request JSON body:

{
  "roleId": " ROLE_NAME 
",
  "title": " ROLE_TITLE 
",
  "description": " ROLE_DESCRIPTION 
",
  "includedPermissions": [
    " PERMISSION_1 
",
    " PERMISSION_2 
"
  ],
  "stage": " LAUNCH-STAGE 
",
  "etag": " ETAG 
"
}

To send your request, expand one of these options:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/ RESOURCE_TYPE 
/ RESOURCE_ID 
/roles"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method PATCH `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://iam.googleapis.com/v1/ RESOURCE_TYPE 
/ RESOURCE_ID 
/roles" | Select-Object -Expand Content

The response contains an abbreviated role definition that includes the role name, the fields that you updated, and an etag that identifies the current version of the role.

{
  "name": "projects/test-project-1000092/roles/myCompanyAdmin",
  "title": "My Updated Company Admin",
  "includedPermissions": [
    "storage.buckets.get",
    "storage.buckets.list"
  ],
  "stage": "BETA",
  "etag": "BwWoyDpAxBc="
}