Method: projects.roles.delete

Soft deletes a role. The role is suspended and cannot be used to create new IAM Policy Bindings. The Role will not be included in roles.list() unless showDeleted is set in the ListRolesRequest. The Role contains the deleted boolean set. Existing Bindings remains, but are inactive. The Role can be undeleted within 7 days. After 7 days the Role is deleted and all Bindings associated with the role are removed.

HTTP request


The URL uses gRPC Transcoding syntax.

Path parameters



The name parameter's value depends on the target resource for the request, namely projects or organizations. Each resource type's name value format is described below:

  • projects.roles.delete(): projects/{PROJECT_ID}/roles/{CUSTOM_ROLE_ID}. This method deletes only custom roles that have been created at the project level. Example request URL:{PROJECT_ID}/roles/{CUSTOM_ROLE_ID}

  • organizations.roles.delete(): organizations/{ORGANIZATION_ID}/roles/{CUSTOM_ROLE_ID}. This method deletes only custom roles that have been created at the organization level. Example request URL:{ORGANIZATION_ID}/roles/{CUSTOM_ROLE_ID}

Note: Wildcard (*) values are invalid; you must specify a complete project ID or organization ID.

Authorization requires the following Google IAM permission on the specified resource name:

  • iam.roles.delete

Query parameters


string (bytes format)

Used to perform a consistent read-modify-write.

A base64-encoded string.

Request body

The request body must be empty.

Response body

If successful, the response body contains an instance of Role.

Authorization Scopes

Requires one of the following OAuth scopes:


For more information, see the Authentication Overview.