gcloud

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

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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 thegcloud iam list-testable-permissions command to get a list of permissions that are available for custom roles in a specific project or organization. The response lists the permissions that you can use in custom roles for that project or organization.

   To list permissions that are available in custom roles for a project or organization, run this command:

   gcloud iam list-testable-permissionsFULL_RESOURCE_NAME \    --filter="customRolesSupportLevel!=NOT_SUPPORTED"

   ReplaceFULL_RESOURCE_NAME with one of the following values:

   • Project://cloudresourcemanager.googleapis.com/projects/PROJECT_ID (for example,//cloudresourcemanager.googleapis.com/projects/my-project)

   • Organization://cloudresourcemanager.googleapis.com/organizations/NUMERIC_ID (for example,//cloudresourcemanager.googleapis.com/organizations/123456789012)

   The results indicate whether each permission is supported in custom roles. Permissions that do not have acustomRolesSupportLevel field are fully supported.

   Thelist-testable-permissions command might return hundreds of results. This partial example shows the format of each result:

   ---name: appengine.applications.createstage: GA---customRolesSupportLevel: TESTINGname: appengine.applications.disablestage: GA---name: appengine.applications.getstage: GA---name: appengine.applications.updatestage: GA---name: appengine.instances.deletestage: GA---name: appengine.instances.getstage: GA---

C++

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

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

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&resource){iam::IAMClientclient(iam::MakeIAMConnection());google::iam::admin::v1::QueryTestablePermissionsRequestrequest;request.set_full_resource_name(resource);intcount=0;for(auto&permission:client.QueryTestablePermissions(request)){if(!permission)throwstd::move(permission).status();std::cout <<"Permission successfully retrieved: " <<permission->name()              <<"\n";++count;}if(count==0){std::cout <<"No testable permissions found in resource: " <<resource              <<"\n";}}

C#

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

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

usingSystem;usingSystem.Collections.Generic;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticIList<Permission>QueryTestablePermissions(stringfullResourceName){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});varrequest=newQueryTestablePermissionsRequest{FullResourceName=fullResourceName};varresponse=service.Permissions.QueryTestablePermissions(request).Execute();foreach(varpinresponse.Permissions){Console.WriteLine(p.Name);}returnresponse.Permissions;}}

Go

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

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

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// queryTestablePermissions lists testable permissions on a resource.funcqueryTestablePermissions(wio.Writer,fullResourceNamestring)([]*iam.Permission,error){ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnnil,fmt.Errorf("iam.NewService: %w",err)}request:=&iam.QueryTestablePermissionsRequest{FullResourceName:fullResourceName,}response,err:=service.Permissions.QueryTestablePermissions(request).Do()iferr!=nil{returnnil,fmt.Errorf("Permissions.QueryTestablePermissions: %w",err)}for_,p:=rangeresponse.Permissions{fmt.Fprintf(w,"Found permissions: %v",p.Name)}returnresponse.Permissions,nil}

Java

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

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

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.cloud.iam.admin.v1.IAMClient.QueryTestablePermissionsPagedResponse;importcom.google.iam.admin.v1.QueryTestablePermissionsRequest;importjava.io.IOException;/** View available permissions in a project. */publicclassQueryTestablePermissions{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variable before running the sample.// Full resource names can take one of the following forms:// cloudresourcemanager.googleapis.com/projects/PROJECT_ID// cloudresourcemanager.googleapis.com/organizations/NUMERIC_IDStringfullResourceName="your-full-resource-name";queryTestablePermissions(fullResourceName);}publicstaticvoidqueryTestablePermissions(StringfullResourceName)throwsIOException{QueryTestablePermissionsRequestqueryTestablePermissionsRequest=QueryTestablePermissionsRequest.newBuilder().setFullResourceName(fullResourceName).build();try(IAMClientiamClient=IAMClient.create()){QueryTestablePermissionsPagedResponsequeryTestablePermissionsPagedResponse=iamClient.queryTestablePermissions(queryTestablePermissionsRequest);queryTestablePermissionsPagedResponse.iterateAll().forEach(permission->System.out.println(permission.getName()));}}}

Python

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

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

importosfromtypingimportListfromgoogle.cloudimportresourcemanager_v3fromgoogle.iam.v1importiam_policy_pb2,policy_pb2defquery_testable_permissions(project_id:str,permissions:List[str])->policy_pb2.Policy:"""Tests IAM permissions of the caller.    project_id: ID or number of the Google Cloud project you want to use.    permissions: List of permissions to get.    """client=resourcemanager_v3.ProjectsClient()request=iam_policy_pb2.TestIamPermissionsRequest()request.resource=f"projects/{project_id}"request.permissions.extend(permissions)permissions_reponse=client.test_iam_permissions(request)print(permissions_reponse)returnpermissions_reponse.permissions

REST

Thepermissions.queryTestablePermissions method lists permissions available in an organization or project.

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

• FULL_RESOURCE_NAME: A URI consisting ofthe service name and the path to the resource. For examples, seeFull resource names.
• PAGE_SIZE: Optional. The number of permissions to include in the response. The default value is 100, and the maximum value is 1,000. If the number of permissions is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
• NEXT_PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of testable permissions will start where the previous response ended.

HTTP method and URL:

POST https://iam.googleapis.com/v1/permissions:queryTestablePermissions

Request JSON body:

{  "fullResourceName": "FULL_RESOURCE_NAME"  "pageSize":PAGE_SIZE,  "pageToken": "NEXT_PAGE_TOKEN"}

To send your request, expand one of these options:

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

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

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

The response contains the list of permissions.

{  "permissions": [    {      "name": "iam.serviceAccountKeys.create",      "stage": "GA"    },    {      "name": "iam.serviceAccountKeys.delete",      "stage": "GA"    },    {      "name": "iam.serviceAccountKeys.get",      "stage": "GA"    }  ],  "nextPageToken": "CgoHBajEfjUDQyABEPaIv5vIiMDTVhgDIhtpYW0uc2VydmljZUFjY291bnRLZXlzLmxpc3Q"}

Console

1. In the Google Cloud console, go to theRoles page.

   Go to the Roles page

2. Select your organization or project from the drop-down list at the top ofthe page.

3. Select the checkbox for one or more roles to view the role permissions.The right side panel displays the permissions contained in the role(s),if any.

The icons in theType column indicate if it's a custom role("factory" icon) or a predefined role(hexagon icon).

If you want to find all the roles that include a specific permission, typethe permission name in theFilter box at the top of the Roles list.

gcloud

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

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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 thegcloud iam roles describe command to view metadata for predefined roles and custom roles.

   To view the metadata for a predefined role, execute the following command:

   gcloud iam roles describeROLE_ID

   ROLE_ID is the ID of the role. Predefined roles include therole prefix in their IDs, for example,roles/iam.roleViewer.

   The following example demonstrates the output of thedescribe command when executed on the predefined roleroles/iam.roleViewer:

   gcloud iam roles describe roles/iam.roleViewer

   description:Read access to all custom roles in the project.etag:AA==includedPermissions:-iam.roles.get-iam.roles.list-resourcemanager.projects.get-resourcemanager.projects.getIamPolicyname:roles/iam.roleViewerstage:GAtitle:Role Viewer

   To view the metadata for a custom role, execute one of the following commands:

   • To view the metadata for a custom role created at the organization level, execute the following command:

     gcloud iam roles describe --organization=ORGANIZATION_IDROLE_ID

   • To view the metadata for a custom role created at the project level, execute the following command:

     gcloud iam roles describe --project=PROJECT_IDROLE_ID

   Each placeholder value is described below:

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-project.

   • ROLE_ID is the ID of the role, excluding any prefixes likeprojects/,organizations/, orroles/. For example,myCompanyAdmin.

   For more information, see the reference documentation forgcloud iam roles describe.

C++

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

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

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&name){iam::IAMClientclient(iam::MakeIAMConnection());google::iam::admin::v1::GetRoleRequestrequest;request.set_name(name);autoresponse=client.GetRole(request);if(!response)throwstd::move(response).status();std::cout <<"Role successfully retrieved: " <<response->DebugString()            <<"\n";}

C#

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

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

usingSystem;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticRoleGetRole(stringname){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});varrole=service.Roles.Get(name).Execute();Console.WriteLine(role.Name);Console.WriteLine(String.Join(", ",role.IncludedPermissions));returnrole;}}

Go

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

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

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// getRole gets role metadata.funcgetRole(wio.Writer,namestring)(*iam.Role,error){ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnnil,fmt.Errorf("iam.NewService: %w",err)}role,err:=service.Roles.Get(name).Do()iferr!=nil{returnnil,fmt.Errorf("Roles.Get: %w",err)}fmt.Fprintf(w,"Got role: %v\n",role.Name)for_,permission:=rangerole.IncludedPermissions{fmt.Fprintf(w,"Got permission: %v\n",permission)}returnrole,nil}

Java

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

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

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.GetRoleRequest;importcom.google.iam.admin.v1.Role;importjava.io.IOException;/** Get role metadata. Specifically, printing out role permissions. */publicclassGetRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variable before running the sample.StringroleId="a unique identifier (e.g. testViewer)";getRole(roleId);}publicstaticvoidgetRole(StringroleId)throwsIOException{GetRoleRequestgetRoleRequest=GetRoleRequest.newBuilder().setName(roleId).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){Rolerole=iamClient.getRole(getRoleRequest);role.getIncludedPermissionsList().forEach(permission->System.out.println(permission));}}}

Python

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

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

fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.iam_admin_v1importGetRoleRequest,IAMClient,Roledefget_role(project_id:str,role_id:str)->Role:client=IAMClient()name=f"projects/{project_id}/roles/{role_id}"request=GetRoleRequest(name=name)try:role=client.get_role(request)print(f"Retrieved role:{role_id}:{role}")returnroleexceptNotFoundasexc:raiseNotFound(f"Role with id [{role_id}] not found, take some actions")fromexc

REST

Theroles.get method gets the definition of a role.

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

• ROLE_NAME: The full role name, including anyorganizations/,projects/, orroles/ prefixes. For example,organizations/123456789012/roles/myCompanyAdmin.

HTTP method and URL:

GET https://iam.googleapis.com/v1/ROLE_NAME

To send your request, expand one of these options:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/ROLE_NAME"

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/ROLE_NAME" | Select-Object -Expand Content

The response contains the role definition.

{  "name": "projects/my-project/roles/customRole",  "title": "My Custom Role",  "description": "My custom role description.",  "includedPermissions": [    "storage.buckets.get",    "storage.buckets.list"  ],  "etag": "BwWiPg2fmDE="}

Console

The following warning message is displayed:"Not applicable for project-level custom roles". Thepermission will be automatically unselected from the list of includedpermissions, and you can proceed with creating the role.

gcloud

The following error messageis returned:INVALID_ARGUMENT: PermissionPERMISSION is notvalid. The custom role will not be created until you first remove thepermission from the role definition and trythe operation again.

REST API

The following error message is returned:PermissionPERMISSION is not valid, along with anHTTP 400 error code and a status ofINVALID_ARGUMENT. The custom role willnot be created until you first remove the permission from the roledefinition and try the operation again.

Console

Some predefined roles contain deprecated permissions or permissions that areotherwise not permitted in custom roles. If you try to create a custom rolebased on one of these predefined roles, the custom role will omit the deprecatedand restricted permissions.

To create a new custom role from scratch:

1. In the Google Cloud console, go to theRoles page.

   Go to the Roles page

2. Using the drop-down list at the top of the page, select the organization orproject in which you want to create a role.

3. ClickCreate Role.

4. Enter aTitle,Description,ID, andRole launch stagefor the role. The role ID cannot be changed after the role is created.

5. ClickAdd Permissions.

6. Select the permissions you want to include in the role and clickAddPermissions. Use theAll Services andAll Types drop-down lists tofilter and select permissions by services and types.

Creating a custom role based on an existing predefined role:

1. In the Google Cloud console, go to theRoles page.

   Go to the Roles page

2. Select the organization or project in which you want to create a role.
3. Select the roles on which you want to base the new custom role.
4. ClickCreate Role from Selection.
5. Enter aTitle,Description,ID, andRole launch stagefor the role. The role ID cannot be changed after the role is created.
6. Uncheck the permissions you want to exclude from the role.
7. ClickAdd Permissions to include any permissions.
8. ClickCreate.

gcloud

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

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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 thegcloud iam roles create command to create new custom roles. You can use this command in two ways:

   • By providing a YAML file that contains the role definition

   • By using flags to specify the role definition

   When creating 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.

   A custom role can contain onlypermissions that are supported in custom roles. If the custom role contains other permissions, the command fails.

   To create a custom role using a YAML file:

   Create a YAML file that contains the definition for your custom role. The file must be structured in the following way:

   title:ROLE_TITLEdescription:ROLE_DESCRIPTIONstage:LAUNCH_STAGEincludedPermissions:-PERMISSION_1-PERMISSION_2

   Each placeholder value is described below:

   • 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 asALPHA,BETA, orGA.

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

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

   • To create a custom role at the organization level, execute the following command:

     gcloud iam roles createROLE_ID--organization=ORGANIZATION_ID \    --file=YAML_FILE_PATH

   • To create a custom role at the project level, execute the following command:

     gcloud iam roles createROLE_ID --project=PROJECT_ID \    --file=YAML_FILE_PATH

   Each placeholder value is described below:

   • ROLE_ID is the name of the role, such asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-project.

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

   Examples

   The following example YAML file demonstrates how to create a role definition:

   title:"MyCompanyAdmin"description:"Mycustomroledescription."stage:"ALPHA"includedPermissions:-iam.roles.get-iam.roles.list

   The following example demonstrates how to create a role at the organization level using the YAML file:

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

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

   Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin

   The following example demonstrates how to create a role at the project level using the YAML file:

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

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

   Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin

   To create a custom role using flags:

   Execute one of the following commands:

   • To create a custom role at the organization level, execute the following command:

     gcloud iam roles createROLE_ID--organization=ORGANIZATION_ID \    --title=ROLE_TITLE --description=ROLE_DESCRIPTION \    --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

   • To create a custom role at the project level, execute the following command:

     gcloud iam roles createROLE_ID --project=PROJECT_ID \    --title=ROLE_TITLE --description=ROLE_DESCRIPTION \    --permissions="PERMISSIONS_LIST" --stage=LAUNCH_STAGE

   Each placeholder value is described below:

   • ROLE_ID is the name of the role, such asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-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.".

   • PERMISSIONS_LIST contains a comma-separated list of permissions you want to include in the custom role. For example:iam.roles.get,iam.roles.list. You can't use wildcard characters (*) in permission names.

   • LAUNCH_STAGE indicates the stage of a role in the launch lifecycle, such asALPHA,BETA, orGA.

   Examples

   The following example demonstrates how to create a role at the organization level using flags:

   gcloud iam roles create myCompanyAdmin --organization=123456789012 \    --title="My Company Admin" --description="My custom role description." \    --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA

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

   Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin

   The following example demonstrates how to create a role at the project level using flags:

   gcloud iam roles create myCompanyAdmin --project=my-project \    --title="My Company Admin" --description="My custom role description." \    --permissions="iam.roles.get,iam.roles.list" --stage=ALPHA

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

   Created role [myCompanyAdmin].description:My custom role description.etag:BwVkBX0sQD0=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin

C++

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

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

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&parent,std::stringconst&role_id,std::vector<std::string>const&included_permissions){iam::IAMClientclient(iam::MakeIAMConnection());google::iam::admin::v1::CreateRoleRequestrequest;request.set_parent("projects/"+parent);request.set_role_id(role_id);google::iam::admin::v1::Rolerole;role.set_stage(google::iam::admin::v1::Role::GA);for(autoconst&permission:included_permissions){*role.add_included_permissions()=permission;}*request.mutable_role()=role;autoresponse=client.CreateRole(request);if(!response)throwstd::move(response).status();std::cout <<"Role successfully created: " <<response->DebugString()            <<"\n";}

C#

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

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

usingSystem;usingSystem.Collections.Generic;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticRoleCreateRole(stringname,stringprojectId,stringtitle,stringdescription,IList<string>permissions,stringstage){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});varrole=newRole{Title=title,Description=description,IncludedPermissions=permissions,Stage=stage};varrequest=newCreateRoleRequest{Role=role,RoleId=name};role=service.Projects.Roles.Create(request,"projects/"+projectId).Execute();Console.WriteLine("Created role: "+role.Name);returnrole;}}

Go

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

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

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// createRole creates a custom role.funccreateRole(wio.Writer,projectID,name,title,description,stagestring,permissions[]string)(*iam.Role,error){ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnnil,fmt.Errorf("iam.NewService: %w",err)}request:=&iam.CreateRoleRequest{Role:&iam.Role{Title:title,Description:description,IncludedPermissions:permissions,Stage:stage,},RoleId:name,}role,err:=service.Projects.Roles.Create("projects/"+projectID,request).Do()iferr!=nil{returnnil,fmt.Errorf("Projects.Roles.Create: %w",err)}fmt.Fprintf(w,"Created role: %v",role.Name)returnrole,nil}

Java

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

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

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.CreateRoleRequest;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.Role.RoleLaunchStage;importjava.io.IOException;importjava.util.Arrays;/** Create role. */publicclassCreateRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.StringprojectId="your-project-id";StringroleId="a unique identifier (e.g. testViewer)";Stringtitle="a title for your role (e.g. IAM Role Viewer)";Stringdescription="a description of the role";Iterable<String>includedPermissions=Arrays.asList("roles/iam.roleViewer","roles/logging.viewer");createRole(projectId,title,description,includedPermissions,roleId);}publicstaticvoidcreateRole(StringprojectId,Stringtitle,Stringdescription,Iterable<String>includedPermissions,StringroleId)throwsIOException{Role.BuilderroleBuilder=Role.newBuilder().setTitle(title).setDescription(description).addAllIncludedPermissions(includedPermissions)// See launch stage enums at// https://cloud.google.com/iam/docs/reference/rpc/google.iam.admin.v1#rolelaunchstage.setStage(RoleLaunchStage.BETA);CreateRoleRequestcreateRoleRequest=CreateRoleRequest.newBuilder().setParent("projects/"+projectId).setRoleId(roleId).setRole(roleBuilder).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){Roleresult=iamClient.createRole(createRoleRequest);System.out.println("Created role: "+result.getName());}}}

Python

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

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

fromtypingimportList,Optionalfromgoogle.api_core.exceptionsimportAlreadyExists,FailedPreconditionfromgoogle.cloud.iam_admin_v1importCreateRoleRequest,IAMClient,Roledefcreate_role(project_id:str,role_id:str,permissions:List[str],title:Optional[str]=None)->Role:"""Creates iam role with given parameters.    Args:        project_id: GCP project id        role_id: id of GCP iam role        permissions: list of iam permissions to assign to role. f.e ["iam.roles.get", "iam.roles.list"]        title: title for iam role. role_id will be used in case of None    Returns: google.cloud.iam_admin_v1.Role object    """client=IAMClient()parent=f"projects/{project_id}"request=CreateRoleRequest(parent=parent,role_id=role_id,role=Role(title=title,included_permissions=permissions),)try:role=client.create_role(request)print(f"Created iam role:{role_id}:{role}")returnroleexceptAlreadyExists:print(f"Role with id [{role_id}] already exists, take some actions")exceptFailedPrecondition:print(f"Role with id [{role_id}] already exists and in deleted state, take some actions")

REST

Theroles.create method creates a custom role in a project or organization.

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

• RESOURCE_TYPE: The resource type whosecustom roles you want to manage. Use the valueprojects ororganizations.
• RESOURCE_ID: The project ID ororganization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, likemy-project. Organization IDs are numeric, like123456789012.
• ROLE_ID: The name of the role, such asmyCompanyAdmin.
• ROLE_TITLE: The human-readable title for therole. For example,My Company Admin.
• ROLE_DESCRIPTION: A description for therole. For example,"The company admin role allows company admins to access importantresources".

• PERMISSION_1 andPERMISSION_2: The permissions that you want to include in the role. Forexample,storage.objects.update. You can't use wildcard characters (*) inpermission names.

  A custom role can contain onlypermissions that are supported in custom roles. If the custom role contains other permissions, the request fails.

• LAUNCH_STAGE: The current launch stage of therole. This field can contain one of the following values:EAP,ALPHA,BETA,GA,DEPRECATED, orDISABLED.

HTTP method and URL:

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

Request JSON body:

{  "roleId": "ROLE_ID",  "role": {    "title": "ROLE_TITLE",    "description": "ROLE_DESCRIPTION",    "includedPermissions": [      "PERMISSION_1",      "PERMISSION_2"    ],    "stage": "LAUNCH_STAGE"  }}

To send your request, expand one of these options:

curl -X POST \
     -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 POST `
    -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 the role you created.

{  "name": "projects/myProject/roles/myCompanyAdmin",  "title": "My Company Admin",  "description": "My custom role description.",  "includedPermissions": [    "iam.roles.get",    "iam.roles.list"  ],  "etag": "BwWox/JbaZw="}

1. In the Google Cloud console, go to theRoles page.

   Go to the Roles page

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

3. Click a custom role.

4. ClickEdit Role.

5. To update the role's metadata, edit the role'sTitle,Description,orRole launch stage.

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

   1. ClickAdd Permissions to add new permissions to the role.
   2. Uncheck permissions to remove permissions from the role.

7. ClickUpdate to 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, aCloud 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 thegcloud 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 describeROLE_ID --organization=ORGANIZATION_ID

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

     gcloud iam roles describeROLE_ID --project=PROJECT_ID

   Each placeholder value is described below:

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

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-project.

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

   Thedescribe command returns the following output:

   description:ROLE_DESCRIPTIONetag:ETAGincludedPermissions:-PERMISSION_1-PERMISSION_2name:ROLE_NAMEstage:LAUNCH_STAGEtitle: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 asBwVkBkbfr70=.

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

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

   • LAUNCH_STAGE indicates the stage of a role in the launch lifecycle, such asALPHA,BETA, orGA.

   • 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 outputtedetag value.

   Consider the following example YAML file, which contains the output from thedescribe 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.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle: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 updateROLE_ID--organization=ORGANIZATION_ID \    --file=YAML_FILE_PATH

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

     gcloud iam roles updateROLE_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 asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-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 updateROLE_ID --organization=ORGANIZATION_ID \    --file=YAML_FILE_PATH

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

     gcloud iam roles updateROLE_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 asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-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.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle: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.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin

   To update a custom role using flags:

   Each part of a role definition can be updated using a corresponding flag. See thegcloud 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 updateROLE_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 updateROLE_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 asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-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 asALPHA,BETA, orGA.

   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.listname:organizations/123456789012/roles/myCompanyAdminstage:ALPHAtitle: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.listname:projects/my-project/roles/myCompanyAdminstage:ALPHAtitle:My Company Admin

C++

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

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

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&name,std::stringconst&title){iam::IAMClientclient(iam::MakeIAMConnection());google::iam::admin::v1::UpdateRoleRequestrequest;request.set_name(name);google::iam::admin::v1::Rolerole;role.set_title(title);google::protobuf::FieldMaskupdate_mask;*update_mask.add_paths()="title";*request.mutable_role()=role;*request.mutable_update_mask()=update_mask;autoresponse=client.UpdateRole(request);if(!response)throwstd::move(response).status();std::cout <<"Role successfully updated: " <<response->DebugString()            <<"\n";}

C#

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

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

usingSystem;usingSystem.Collections.Generic;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticRoleEditRole(stringname,stringprojectId,stringnewTitle,stringnewDescription,IList<string>newPermissions,stringnewStage){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});// First, get a Role using List() or Get().stringresource=$"projects/{projectId}/roles/{name}";varrole=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);returnrole;}}

Go

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

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

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

Java

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

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

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.Role.RoleLaunchStage;importcom.google.iam.admin.v1.UpdateRoleRequest;importcom.google.protobuf.FieldMask;importjava.io.IOException;/** Edit role metadata. Specifically, update description and launch stage. */publicclassEditRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.// Role ID must point to an existing role.StringprojectId="your-project-id";StringroleId="a unique identifier (e.g. testViewer)";Stringdescription="a new description of the role";editRole(projectId,roleId,description);}publicstaticvoideditRole(StringprojectId,StringroleId,Stringdescription)throwsIOException{StringroleName="projects/"+projectId+"/roles/"+roleId;Role.BuilderroleBuilder=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);FieldMaskfieldMask=FieldMask.newBuilder().addPaths("description").addPaths("stage").build();UpdateRoleRequestupdateRoleRequest=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(IAMClientiamClient=IAMClient.create()){Roleresult=iamClient.updateRole(updateRoleRequest);System.out.println("Edited role:\n"+result);}}}

Python

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

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

fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.iam_admin_v1importIAMClient,Role,UpdateRoleRequestfromsnippets.get_roleimportget_roledefedit_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}")returnroleexceptNotFound:print(f"Role [{role.name}] not found, take some actions")

REST

Theroles.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 whosecustom roles you want to manage. Use the valueprojects ororganizations.
• RESOURCE_ID: The project ID ororganization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, likemy-project. Organization IDs are numeric, like123456789012.
• ROLE_NAME: The full role name, including anyorganizations/,projects/, orroles/ 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 therole. For example,My Company Admin.
• ROLE_DESCRIPTION: A description for therole. For example,"The company admin role allows company admins to access importantresources".
• PERMISSION_1 andPERMISSION_2: The permissions that you want to include in the role. Forexample,storage.objects.update. You can't use wildcard characters (*) inpermission names.
• LAUNCH_STAGE: The current launch stage of therole. This field can contain one of the following values:EAP,ALPHA,BETA,GA,DEPRECATED, orDISABLED.

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="}

Console

1. In the Google Cloud console, go to theRoles page.

   Go to the Roles page

2. Click "Select a project" drop-down list at the top of the page.

3. Select your organization or project.

4. Select a custom role and clickDisable.

gcloud

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

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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 thegcloud iam roles update command to disable a custom role by setting its launch stage toDISABLED.

   As described in thegcloud tab of theEditing an existing custom role section, you can update an existing custom role in the following two ways:

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

   • By using flags to specify the updated role definition

   The easiest way to disable an existing custom role is to use the--stage flag and set it toDISABLED. Execute one of the following commands:

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

     gcloud iam roles updateROLE_ID--organization=ORGANIZATION_ID \    --stage=DISABLED

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

     gcloud iam roles updateROLE_ID --project=PROJECT_ID \    --stage=DISABLED

   Each placeholder value is described below:

   • ROLE_ID is the name of the role, such asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-project.

   Examples

   The following example demonstrates how to disable an organization-level role:

   gcloud iam roles update myCompanyAdmin --organization=123456789012 \    --stage=DISABLED

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

   description:My custom role description.etag:BwVkB5NLIQw=includedPermissions:-iam.roles.get-iam.roles.listname:organizations/123456789012/roles/myCompanyAdminstage:DISABLEDtitle:My Company Admin

   The following example demonstrates how to disable a project-level role:

   gcloud iam roles update myCompanyAdmin --project=my-project \    --stage=DISABLED

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

   description:My custom role description.etag:BwVkB5NLIQw=includedPermissions:-iam.roles.get-iam.roles.listname:projects/my-project/roles/myCompanyAdminstage:DISABLEDtitle:My Company Admin

C++

Updatethestage field of the role toDISABLED.

C#

Updatethestage field of the role toDISABLED.

Go

Updatethestage field of the role toDISABLED.

Java

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

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

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.Role;importcom.google.iam.admin.v1.UpdateRoleRequest;importcom.google.protobuf.FieldMask;importjava.io.IOException;publicclassDisableRole{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.// Role ID must point to an existing role.StringprojectId="your-project-id";StringroleId="testRole";Rolerole=disableRole(projectId,roleId);System.out.println("Role name: "+role.getName());System.out.println("Role stage: "+role.getStage());}publicstaticRoledisableRole(StringprojectId,StringroleId)throwsIOException{StringroleName="projects/"+projectId+"/roles/"+roleId;Rolerole=Role.newBuilder().setName(roleName).setStage(Role.RoleLaunchStage.DISABLED).build();FieldMaskfieldMask=FieldMask.newBuilder().addPaths("stage").build();UpdateRoleRequestupdateRoleRequest=UpdateRoleRequest.newBuilder().setName(roleName).setRole(role).setUpdateMask(fieldMask).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){returniamClient.updateRole(updateRoleRequest);}}}

Python

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

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

fromgoogle.api_core.exceptionsimportNotFoundfromgoogle.cloud.iam_admin_v1importGetRoleRequest,IAMClient,Role,UpdateRoleRequestdefdisable_role(project_id:str,role_id:str)->Role:"""Disables an IAM role in a GCP project.    Args:        project_id: GCP project ID        role_id: ID of GCP IAM role    Returns: Updated google.cloud.iam_admin_v1.Role object with disabled stage    """client=IAMClient()name=f"projects/{project_id}/roles/{role_id}"get_request=GetRoleRequest(name=name)try:role=client.get_role(get_request)role.stage=Role.RoleLaunchStage.DISABLEDupdate_request=UpdateRoleRequest(name=role.name,role=role)client.update_role(update_request)print(f"Disabled role:{role_id}:{role}")returnroleexceptNotFoundasexc:raiseNotFound(f'Role with id [{role_id}] not found, take some actions')fromexc

REST

Theroles.patch method lets you change a custom role's launch stage toDISABLED,which disables the role.

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

• RESOURCE_TYPE: The resource type whosecustom roles you want to manage. Use the valueprojects ororganizations.
• RESOURCE_ID: The project ID ororganization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, likemy-project. Organization IDs are numeric, like123456789012.
• ROLE_NAME: The full role name, including anyorganizations/,projects/, orroles/ prefixes. For example,organizations/123456789012/roles/myCompanyAdmin.
• ETAG: An identifier for a version of the role.Include this field to prevent overwriting other role changes.

HTTP method and URL:

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

Request JSON body:

{  "roleId": "ROLE_NAME",  "stage": DISABLED,  "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

You should receive a JSON response similar to the following:

{  "name": "projects/test-project-1000092/roles/myCompanyAdmin","stage": "DISABLED",  "etag": "BwWoyDpAxBc="}

Console

In the Google Cloud console, go to theRoles page.

Go to the Roles page

All the custom roles for the organization or project that you have selected arelisted on the page.

gcloud

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

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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 thegcloud iam roles list command to list custom roles and predefined roles for a project or organization:

   • To list organization-level custom roles, execute the following command:

     gcloud iam roles list --organization=ORGANIZATION_ID

   • To list project-level custom roles, execute the following command:

     gcloud iam roles list --project=PROJECT_ID

   Each placeholder value is described below:

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-project.

   To list deleted roles, you can also specify the--show-deleted flag.

   Execute the following command to list predefined roles:

   gcloud iam roles list

C++

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

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

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&project){iam::IAMClientclient(iam::MakeIAMConnection());intcount=0;google::iam::admin::v1::ListRolesRequestrequest;request.set_parent(project);for(auto&role:client.ListRoles(request)){if(!role)throwstd::move(role).status();std::cout <<"Roles successfully retrieved: " <<role->name() <<"\n";++count;}if(count==0){std::cout <<"No roles found in project: " <<project <<"\n";}}

C#

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

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

usingSystem;usingSystem.Collections.Generic;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticIList<Role>ListRoles(stringprojectId){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});varresponse=service.Projects.Roles.List("projects/"+projectId).Execute();foreach(varroleinresponse.Roles){Console.WriteLine(role.Name);}returnresponse.Roles;}}

Go

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

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

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// listRoles lists a project's roles.funclistRoles(wio.Writer,projectIDstring)([]*iam.Role,error){ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnnil,fmt.Errorf("iam.NewService: %w",err)}response,err:=service.Projects.Roles.List("projects/"+projectID).Do()iferr!=nil{returnnil,fmt.Errorf("Projects.Roles.List: %w",err)}for_,role:=rangeresponse.Roles{fmt.Fprintf(w,"Listing role: %v\n",role.Name)}returnresponse.Roles,nil}

Java

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

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

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.cloud.iam.admin.v1.IAMClient.ListRolesPagedResponse;importcom.google.iam.admin.v1.ListRolesRequest;importjava.io.IOException;/** List roles in a project. */publicclassListRoles{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variable before running the sample.StringprojectId="your-project-id";listRoles(projectId);}publicstaticvoidlistRoles(StringprojectId)throwsIOException{ListRolesRequestlistRolesRequest=ListRolesRequest.newBuilder().setParent("projects/"+projectId).build();// Initialize client for sending requests. This client only needs to be created// once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){ListRolesPagedResponselistRolesResponse=iamClient.listRoles(listRolesRequest);listRolesResponse.iterateAll().forEach(role->System.out.println(role));}}}

Python

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

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

fromgoogle.cloud.iam_admin_v1importIAMClient,ListRolesRequest,RoleViewfromgoogle.cloud.iam_admin_v1.services.iam.pagersimportListRolesPagerdeflist_roles(project_id:str,show_deleted:bool=True,role_view:RoleView=RoleView.BASIC)->ListRolesPager:"""Lists IAM roles in a GCP project.    Args:        project_id: GCP project ID        show_deleted: Whether to include deleted roles in the results        role_view: Level of detail for the returned roles (e.g., BASIC or FULL)    Returns: A pager for traversing through the roles    """client=IAMClient()parent=f"projects/{project_id}"request=ListRolesRequest(parent=parent,show_deleted=show_deleted,view=role_view)roles=client.list_roles(request)forpageinroles.pages:forroleinpage.roles:print(role)print("Listed all iam roles")returnroles

REST

Theroles.list method lists all of the custom roles in a project or organization.

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

• RESOURCE_TYPE: The resource type whosecustom roles you want to manage. Use the valueprojects ororganizations.
• RESOURCE_ID: The project ID ororganization ID whose custom roles you want to manage. Project IDs are alphanumeric strings, likemy-project. Organization IDs are numeric, like123456789012.
• ROLE_VIEW: Optional. The information to include for the returned roles. To include the roles' permissions, set this field toFULL. To exclude the roles' permissions, set this field toBASIC. The default value isBASIC.
• PAGE_SIZE: Optional. The number of roles to include in the response. The default value is 300, and the maximum value is 1,000. If the number of roles is greater than the page size, the response contains a pagination token that you can use to retrieve the next page of results.
• NEXT_PAGE_TOKEN: Optional. The pagination token returned in an earlier response from this method. If specified, the list of roles will start where the previous request ended.

GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{  "roles": [    {      "name": "projects/my-project/roles/customRole1",      "title": "First Custom Role",      "description": "Created on: 2020-06-01",      "etag": "BwWiPg2fmDE="    },    {      "name": "projects/my-project/roles/customRole2",      "title": "Second Custom Role",      "description": "Created on: 2020-06-07",      "etag": "BwWiuX53Wi0="    }  ]}

1. In the Google Cloud console, go to theRoles page.

   Go to the Roles page

2. Select the role you wish to delete and clickdeleteDelete on thetop of the page.

gcloud

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

   Activate Cloud Shell

   At the bottom of the Google Cloud console, aCloud 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 thegcloud iam roles delete command to delete a custom role:

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

     gcloud iam roles deleteROLE_ID --organization=ORGANIZATION_ID

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

     gcloud iam roles deleteROLE_ID --project=PROJECT_ID

   Each placeholder value is described below:

   • ROLE_ID is the name of the role, such asmyCompanyAdmin.

   • ORGANIZATION_ID is the numeric ID of the organization, such as123456789012.

   • PROJECT_ID is the name of the project, such asmy-project.

   The role will not be included ingcloud iam roles list, unless the--show-deleted flag is included. Deleted roles are indicated by thedeleted: true block in alist response, such as:

   ---deleted: truedescription: My custom role description.etag: BwVkB5NLIQw=name: projects/my-project/roles/myCompanyAdmintitle: My Company Admin---

C++

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

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

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&name){iam::IAMClientclient(iam::MakeIAMConnection());google::iam::admin::v1::DeleteRoleRequestrequest;request.set_name(name);autoresponse=client.DeleteRole(request);if(!response)throwstd::move(response).status();std::cout <<"Role successfully deleted: " <<response->DebugString()            <<"\n";}

C#

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

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

usingSystem;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassCustomRoles{publicstaticvoidDeleteRole(stringname,stringprojectId){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});service.Projects.Roles.Delete($"projects/{projectId}/roles/{name}").Execute();Console.WriteLine("Deleted role: "+name);}}

Go

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

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

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// deleteRole deletes a custom role.funcdeleteRole(wio.Writer,projectID,namestring)error{ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnfmt.Errorf("iam.NewService: %w",err)}_,err=service.Projects.Roles.Delete("projects/"+projectID+"/roles/"+name).Do()iferr!=nil{returnfmt.Errorf("Projects.Roles.Delete: %w",err)}fmt.Fprintf(w,"Deleted role: %v",name)returnnil}