This page describes how to create and manage Identity and Access Management (IAM) custom roles. Managing roles includes modifying, disabling, listing, deleting, and undeleting roles.
Before you begin
Enable the IAM API.
Set up authentication.
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, 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.
C#
To use the .NET samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
C++
To use the C++ samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
Go
To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
Understand the Google Cloud resource hierarchy.
Required roles
To get the permissions that you need to create and manage custom roles, ask your administrator to grant you the following IAM roles:
-
To manage roles for a project:
Role Administrator (
roles/iam.roleAdmin
) on the project that you want to manage roles for -
To manage roles for an organization:
Organization Role Administrator (
roles/iam.organizationRoleAdmin
) on the organization that you want to manage roles for
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
View available permissions for projects, folders, and organizations
You can create custom roles for an entire organization, or for a specific project in that organization. The permissions that are available for custom roles depend on where you create the role. For example, if a permission can only be used at the organization level, then you can't include that permission in a project-level custom role.
To check which permissions are available for organization-level and project-level custom roles, you can use the gcloud CLI or the Identity and Access Management API to list the permissions that are available in a specific organization or project. For example, you can get all permissions that are available for custom roles that are created in your project.
Some permissions might not be visible to you or usable in a custom role, even if they are supported in custom roles. For example, a permission might not be available for use in custom roles if you have not enabled the API for the service.
To learn more about the permissions that you can add to custom roles, see Supported permissions.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud 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-permissions FULL_RESOURCE_NAME \ --filter="customRolesSupportLevel!=NOT_SUPPORTED"
Replace
FULL_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 a
customRolesSupportLevel
field are fully supported.The
list-testable-permissions
command might return hundreds of results. This partial example shows the format of each result:--- name: appengine.applications.create stage: GA --- customRolesSupportLevel: TESTING name: appengine.applications.disable stage: GA --- name: appengine.applications.get stage: GA --- name: appengine.applications.update stage: GA --- name: appengine.instances.delete stage: GA --- name: appengine.instances.get stage: GA ---
-
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.
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.
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.
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.
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.
REST
The
permissions.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 of the service name and the path to the resource. For examples, see Full 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:
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" }
Get the role metadata
Before you create a custom role, you might want to get the metadata for both predefined and custom roles. Role metadata includes the role ID and permissions contained in the role. You can view the metadata using the Google Cloud console or the IAM API.
To view the role metadata, use one of the methods below:
Console
In the Google Cloud console, go to the Roles page.
Select your organization or project from the drop-down list at the top of the page.
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 the Type column indicate if it's a custom role
or a predefined roleIf you want to find all the roles that include a specific permission, type the permission name in the Filter box at the top of the Roles list.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud 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 describe ROLE_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 the
describe
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.getIamPolicy name: roles/iam.roleViewer stage: GA title: 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_ID ROLE_ID
-
To view the metadata for a custom role created at the project level, execute the following command:
gcloud iam roles describe --project=PROJECT_ID ROLE_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 for
gcloud iam roles describe
. -
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.
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.
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.
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.
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.
REST
The
roles.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:
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=" }
Create a custom role
You can create a custom role at the project or organization level.
An organization-level custom role can include any of the IAM
permissions that are supported in custom
roles. A project-level custom role can
contain any supported permission except for permissions that can only be used
at the organization or folder level, such as
resourcemanager.organizations.get
. If you try to add these permissions to a
project-level custom role, you see an error message:
Console
The following warning message is displayed: "Not applicable for project-level custom roles". The permission will be automatically unselected from the list of included permissions, and you can proceed with creating the role.
gcloud
The following error message
is returned: INVALID_ARGUMENT: Permission PERMISSION is not
valid
. The custom role will not be created until you first remove the
permission from the role definition and try
the operation again.
REST API
The following error message is returned:
Permission PERMISSION is not valid
, along with an
HTTP 400 error code and a status of INVALID_ARGUMENT
. The custom role will
not be created until you first remove the permission from the role
definition and try the operation again.
Each custom role can contain up to 3,000
permissions. Also, the maximum total size of the title, description, and
permission names for a custom role is 64 KB. If you
need to create a larger custom role, you can split the permissions across
multiple custom roles. Choose role titles that show the relationship between the
custom roles, such as Custom Admin (1 of 2)
and Custom Admin (2 of 2)
.
Each custom role can have a launch stage. Most launch stages are informational,
and help you keep track of whether each role is ready for widespread use.
Additionally, the DISABLED
launch stage lets you disable a custom
role. For more information about launch stages, see
Testing and deploying.
Console
Some predefined roles contain deprecated permissions or permissions that are otherwise not permitted in custom roles. If you try to create a custom role based on one of these predefined roles, the custom role will omit the deprecated and restricted permissions.
To create a new custom role from scratch:
In the Google Cloud console, go to the Roles page.
Using the drop-down list at the top of the page, select the organization or project in which you want to create a role.
Click Create Role.
Enter a Title, Description, ID, and Role launch stage for the role. The role ID cannot be changed after the role is created.
Click Add Permissions.
Select the permissions you want to include in the role and click Add Permissions. Use the All Services and All Types drop-down lists to filter and select permissions by services and types.
Creating a custom role based on an existing predefined role:
- In the Google Cloud console, go to the Roles page.
- Select the organization or project in which you want to create a role.
- Select the roles on which you want to base the new custom role.
- Click Create Role from Selection.
- Enter a Title, Description, ID, and Role launch stage for the role. The role ID cannot be changed after the role is created.
- Uncheck the permissions you want to exclude from the role.
- Click Add Permissions to include any permissions.
- Click Create.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud 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 only permissions 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_TITLE description: ROLE_DESCRIPTION stage: LAUNCH_STAGE includedPermissions: - 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 create ROLE_ID--organization=ORGANIZATION_ID \ --file=YAML_FILE_PATH
-
To create a custom role at the project level, execute the following command:
gcloud iam roles create ROLE_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: "My Company Admin" description: "My custom role description." 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.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: 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.list name: projects/my-project/roles/myCompanyAdmin stage: ALPHA title: 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 create ROLE_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 create ROLE_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.list name: organizations/123456789012/roles/myCompanyAdmin stage: ALPHA title: 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.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.
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.
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.
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.
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.
REST
The
roles.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 whose custom roles you want to manage. Use the valueprojects
ororganizations
.RESOURCE_ID
: The project ID or organization 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 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
andPERMISSION_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.A custom role can contain only permissions that are supported in custom roles. If the custom role contains other permissions, the request fails.
LAUNCH_STAGE
: The current launch stage of the role. 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:
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=" }
Edit an existing custom role
A common pattern for updating a resource's metadata, such as a custom role, is the read-modify-write pattern. With this pattern, you read the role's current state, update the data locally, and then send the modified data for writing.
The read-modify-write pattern can cause a conflict if two or more independent
processes attempt the sequence simultaneously. For example, if two owners for a
project try to make conflicting changes to a role at the same time, some changes
could fail. IAM solves this problem using an etag
property in
custom roles. This property is used to verify if the custom role has changed
since the last request. When you make a request to IAM with an
etag value, IAM compares the etag value in the request with the
existing etag value associated with the custom role. It writes the change only
if the etag values match.
When you update a role, first get the role using roles.get()
, update the role,
and then write the updated role using roles.patch()
. Use the etag value when
setting the role only if the corresponding role in roles.get()
contains an
etag value.
Console
In the Google Cloud console, go to the Roles page.
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.
Click a custom role.
Click Edit Role.
To update the role's metadata, edit the role's Title, Description, or Role launch stage.
To update the role's permissions, do the following:
- Click Add Permissions to add new permissions to the role.
- Uncheck permissions to remove permissions from the role.
Click Update to save the edited role.
gcloud
-
In the Google Cloud console, 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.
-
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 asmyCompanyAdmin
. -
ORGANIZATION_ID
is the numeric ID of the organization, such as123456789012
. -
PROJECT_ID
is the name of the project, such asmy-project
.
The
describe
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.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 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 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 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 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 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.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 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.list name: organization/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.
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.
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.
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.
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.
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 valueprojects
ororganizations
.RESOURCE_ID
: The project ID or organization 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 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
andPERMISSION_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
, 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:
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=" }
Disable a custom role
You can disable a custom role by changing its launch stage to DISABLED
. When a
role is disabled, any role bindings related to the role are inactivated,
meaning that granting the role to a user has no effect.
Console
In the Google Cloud console, go to the Roles page.
Click "Select a project" drop-down list at the top of the page.
Select your organization or project.
Select a custom role and click Disable.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud iam roles update
command to disable a custom role by setting its launch stage toDISABLED
.As described in the gcloud tab of the Editing 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 update ROLE_ID--organization=ORGANIZATION_ID \ --stage=DISABLED
-
To disable a project-level role, execute the following command:
gcloud iam roles update ROLE_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.list name: organization/123456789012/roles/myCompanyAdmin stage: DISABLED title: 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.list name: projects/my-project/roles/myCompanyAdmin stage: DISABLED title: My Company Admin
-
C++
Update
the stage
field of the role to DISABLED
.
C#
Update
the stage
field of the role to DISABLED
.
Go
Update
the stage
field of the role to DISABLED
.
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.
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.
REST
The
roles.patch
method lets you change a custom role's launch stage to DISABLED
,
which disables the role.
Before using any of the request data, make the following replacements:
RESOURCE_TYPE
: The resource type whose custom roles you want to manage. Use the valueprojects
ororganizations
.RESOURCE_ID
: The project ID or organization 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:
You should receive a JSON response similar to the following:
{ "name": "projects/test-project-1000092/roles/myCompanyAdmin", "stage": "DISABLED", "etag": "BwWoyDpAxBc=" }
List roles
You can list all custom roles created in your project or organization.
Console
In the Google Cloud console, go to the Roles page.
All the custom roles for the organization or project that you have selected are listed on the page.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud 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, 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.
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.
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.
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.
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.
REST
The
roles.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 whose custom roles you want to manage. Use the valueprojects
ororganizations
.RESOURCE_ID
: The project ID or organization 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.
HTTP method and URL:
GET https://iam.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/roles?view=ROLE_VIEW&pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
To send your request, expand one of these options:
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=" } ] }
Delete a custom role
You can delete any custom role in your project or organization.
Console
In the Google Cloud console, go to the Roles page.
Select the role you wish to delete and click delete Delete on the top of the page.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud iam roles delete
command to delete a custom role:-
To delete an organization-level custom role, execute the following command:
gcloud iam roles delete ROLE_ID --organization=ORGANIZATION_ID
-
To delete a project-level custom role, execute the following command:
gcloud iam roles delete ROLE_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 in
gcloud iam roles list
, unless the--show-deleted
flag is included. Deleted roles are indicated by thedeleted: true
block in alist
response, such as:--- deleted: true description: My custom role description. etag: BwVkB5NLIQw= name: projects/my-project/roles/myCompanyAdmin 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.
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.
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.
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.
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.
REST
The
roles.delete
method deletes a custom role in a project or organization.
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:
DELETE https://iam.googleapis.com/v1/ROLE_NAME
To send your request, expand one of these options:
The response contains the definition of the role that was deleted.
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=", "deleted": true }
When a role is deleted, any role bindings that refer to the role remain in your allow policies, but they have no effect. You can undelete a role within 7 days. During this 7-day period, the Google Cloud console shows that the role was deleted. You can also list deleted roles programmatically, but they are omitted by default.
After 7 to 14 days, the role is scheduled for permanent deletion. At this point, the role no longer counts towards the limit of 300 custom roles per organization or 300 custom roles per project.
The permanent deletion process takes 30 days. During the 30-day window, the role and all associated bindings are permanently removed, and you cannot create a new role with the same role ID.
After the role has been permanently deleted, up to 44 days after the initial deletion request, you can create a new role using the same role ID.
Undelete a custom role
Undeleting a role returns it to its previous state.
Roles can only be undeleted within 7 days. After 7 days, the role can be permanently deleted at any time, and all role bindings that refer to the role are removed.
Console
In the Google Cloud console, go to the Roles page.
Locate the role you wish to undelete, click the more icon at the end of the row, and click Undelete.
gcloud
-
In the Google Cloud console, 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.
-
Use the
gcloud iam roles undelete
command to undelete a custom role:-
To undelete an organization-level custom role, execute the following command:
gcloud iam roles undelete ROLE_ID --organization=ORGANIZATION_ID
-
To undelete a project-level custom role, execute the following command:
gcloud iam roles undelete ROLE_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
.
Examples
The following example demonstrates how to undelete an organization-level custom role:
gcloud iam roles undelete myCompanyAdmin --organization=123456789012
If the role was undeleted successfully, the command's output is similar to the following:
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.list name: organization/123456789012/roles/myCompanyAdmin stage: ALPHA title: My Company Admin
The following example demonstrates how to undelete a project-level custom role:
gcloud iam roles undelete myCompanyAdmin --project=my-project
If the role was undeleted successfully, the command's output is similar to the following:
description: My custom role description. etag: BwVkCAx9W6w= includedPermissions: - iam.roles.get - iam.roles.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.
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.
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.
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.
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.
REST
The
roles.undelete
method undeletes a custom role in a project or organization.
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
.ETAG
: An identifier for a version of the role. Include this field to prevent overwriting other role changes.
HTTP method and URL:
POST https://iam.googleapis.com/v1/ROLE_NAME:undelete
Request JSON body:
{ "etag": "ETAG" }
To send your request, expand one of these options:
The response contains the definition of the role that was undeleted.
{ "name": "projects/my-project/roles/myCompanyAdmin", "title": "My Company Admin", "description": "My custom role description.", "includedPermissions": [ "iam.roles.get", "iam.roles.list" ], "etag": "BwWiPg2fmDE=" }
What's next
- Find out how to grant roles to principals.
- Explore how you can use role recommendations to downscope permissions for principals.
- Learn about conditional role grants, which grant a role only if specific conditions are met.