When you delete a custom role, the following changes occur immediately:
You cannot bind a principal to the custom role in an IAMPolicy.
Existing bindings to the custom role are not changed, but they have no effect.
By default, the response fromroles.listdoes not include the custom role.
A deleted custom role still counts toward thecustom role limituntil it is permanently deleted. You have 7 days to undelete the custom role. After 7 days, the following changes occur:
The custom role is permanently deleted and cannot be recovered.
If an IAM policy contains a binding to the custom role, the binding is permanently removed.
The custom role no longer counts toward your custom role limit.
Thenameparameter's value depends on the target resource for the request, namelyprojectsororganizations. Each resource type'snamevalue format is described below:
projects.roles.delete:projects/{PROJECT_ID}/roles/{CUSTOM_ROLE_ID}. This method deletes onlycustom rolesthat have been created at the project level. Example request URL:https://iam.googleapis.com/v1/projects/{PROJECT_ID}/roles/{CUSTOM_ROLE_ID}
organizations.roles.delete:organizations/{ORGANIZATION_ID}/roles/{CUSTOM_ROLE_ID}. This method deletes onlycustom rolesthat have been created at the organization level. Example request URL:https://iam.googleapis.com/v1/organizations/{ORGANIZATION_ID}/roles/{CUSTOM_ROLE_ID}
Note: Wildcard (*) values are invalid; you must specify a complete project ID or organization ID.
Authorization requires the followingIAMpermission on the specified resourcename:
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-05-21 UTC."],[[["\u003cp\u003eThis endpoint is used to delete a custom Role within either a project or an organization.\u003c/p\u003e\n"],["\u003cp\u003eImmediately upon deletion, the custom role can no longer be used in new IAM policy bindings, and existing bindings become ineffective, though the role is not removed from the list by default.\u003c/p\u003e\n"],["\u003cp\u003eDeleted custom roles are recoverable for 7 days and still count against the custom role limit, after which they are permanently deleted.\u003c/p\u003e\n"],["\u003cp\u003eThe HTTP request for deletion uses the \u003ccode\u003eDELETE\u003c/code\u003e method and requires the role's name, specified in the format \u003ccode\u003eorganizations/*/roles/*\u003c/code\u003e or \u003ccode\u003eprojects/*/roles/*\u003c/code\u003e, to be placed in the path parameters of the URL.\u003c/p\u003e\n"],["\u003cp\u003eAuthorization to delete a role requires the \u003ccode\u003eiam.roles.delete\u003c/code\u003e permission on the specified resource name and one of the provided OAuth scopes.\u003c/p\u003e\n"]]],[],null,["# Method: organizations.roles.delete\n\n- [HTTP request](#body.HTTP_TEMPLATE)\n- [Path parameters](#body.PATH_PARAMETERS)\n- [Query parameters](#body.QUERY_PARAMETERS)\n- [Request body](#body.request_body)\n- [Response body](#body.response_body)\n- [Authorization scopes](#body.aspect)\n- [Examples](#examples)\n- [Try it!](#try-it)\n\nDeletes a custom [Role](/iam/docs/reference/rest/v1/organizations.roles#Role).\n\nWhen you delete a custom role, the following changes occur immediately:\n\n- You cannot bind a principal to the custom role in an IAM [Policy](/iam/docs/reference/rest/v1/Policy).\n- Existing bindings to the custom role are not changed, but they have no effect.\n- By default, the response from [roles.list](/iam/docs/reference/rest/v1/roles/list#google.iam.admin.v1.IAM.ListRoles) does not include the custom role.\n\nA deleted custom role still counts toward the [custom role limit](https://cloud.google.com/iam/help/limits) until it is permanently deleted. You have 7 days to undelete the custom role. After 7 days, the following changes occur:\n\n- The custom role is permanently deleted and cannot be recovered.\n- If an IAM policy contains a binding to the custom role, the binding is permanently removed.\n- The custom role no longer counts toward your custom role limit.\n\n### HTTP request\n\n`DELETE https://iam.googleapis.com/v1/{name=organizations/*/roles/*}`\n\nThe URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.\n\n### Path parameters\n\n### Query parameters\n\n### Request body\n\nThe request body must be empty.\n\n### Response body\n\nIf successful, the response body contains an instance of [Role](/iam/docs/reference/rest/v1/organizations.roles#Role).\n\n### Authorization scopes\n\nRequires one of the following OAuth scopes:\n\n- `https://www.googleapis.com/auth/iam`\n- `\n https://www.googleapis.com/auth/cloud-platform`\n\nFor more information, see the [Authentication Overview](/docs/authentication#authorization-gcp)."]]
