Buckets: setIamPolicy

Updates an Identity and Access Management (IAM) policy for the specified bucket.

Note: This method replaces any existing IAMpolicy set on a bucket. If you want to modify the existing policy, retrieve it with thegetIamPolicy method, edit it as needed, and use the edited version in your setIamPolicy request.

Required permissions

The authenticated user must have thestorage.buckets.setIamPolicy IAMpermission to use this method.

Request

HTTP request

PUT https://storage.googleapis.com/storage/v1/b/bucket/iam

In addition tostandard query parameters, the following query parameters apply to this method.

To see an example of how to include query parameters in a request, see theJSON API Overview page.

Parameters

Parameter nameValueDescription
Path parameters
bucketstring Name of a bucket.

Request body

In the request body, supply data with the following structure:

{  "version":int,  "kind": "storage#policy",  "resourceId":string,  "bindings": [    {      "role":string,      "members": [string      ],      "condition": {        "title":string,        "description":string,        "expression":RFC 3339 format string      }    }],  "etag":string}
Property nameValueDescriptionNotes
versionintTheIAM policy version. Required to be 3 or greater for buckets withIAM Conditions.
kindstringThe kind of item this is. For policies, this field is ignored in a request and is"storage#policy" in a response.
resourceIdstringThe ID of the resource to which this policy belongs. The response for this field is of the form"projects/_/buckets/bucket". This field is ignored in a request.
bindings[]listAn association between a role, which comes with a set of permissions, and principals that have that role.
bindings[].rolestringThe role that principals have. Two types of roles are supported: standard IAM roles, which grant permissions that do not map directly to those provided by ACLs, and legacy IAM roles, which do map directly to ACL permissions. All roles are of the format"roles/storage.specificRole".
SeeCloud Storage IAM Roles for a list of available roles.
bindings[].members[]listA collection of principals that have the specified role. For a list of recognized values, seePrincipal identifiers andConvenience values.
bindings[].conditionobject

A condition object associated with this binding. Each role binding can only contain one condition.

writable
bindings[].condition.titlestring Title of the condition. For example,"expires_end_of_2018".
bindings[].condition.descriptionstring Optional description of the condition. For example,"Expires at midnight on 2018-12-31".writable
bindings[].condition.expressionstringAttribute-based logic expression using a subset of the Common Expression Language (CEL). For example,"request.time < timestamp('2019-01-01T00:00:00Z')".
etagstringHTTP 1.1Entity tag for the policy. Optional. writable

Response

If successful, this method returns a response body with the following structure:

{  "version":int,  "kind": "storage#policy",  "resourceId":string,  "bindings": [    {      "role":string,      "members": [string      ]      "condition": {        "title":string,        "description":string,        "expression":RFC 3339 format string      }    }  ],  "etag":string}
Property nameValueDescriptionNotes
versionintTheIAM policy version.
kindstringThe kind of item this is. For policies, this field is ignored in a request and is"storage#policy" in a response.
resourceIdstringThe ID of the resource to which this policy belongs. The response for this field is of the form"projects/_/buckets/bucket". This field is ignored in a request.
bindings[]listAn association between a role, which comes with a set of permissions, and principals that have that role.
bindings[].rolestringThe role that principals have. Two types of roles are supported: standard IAM roles, which grant permissions that do not map directly to those provided by ACLs, and legacy IAM roles, which do map directly to ACL permissions. All roles are of the format"roles/storage.specificRole".
SeeCloud Storage IAM Roles for a list of available roles.
bindings[].members[]listA collection of identifiers for principals that have the specified role. Recognized identifiers are as follows:
  • "allUsers" — A special identifier that represents any entity on the internet.
  • "allAuthenticatedUsers" — A special identifier that represents most authenticated users, including all service accounts. For more information, seeIAM principals.
  • "user:emailid" — An email address that represents a specific account. For example,"user:joe@example.com".
  • "serviceAccount:emailid" — An email address that represents a service account. For example,"serviceAccount:my-other-app@appspot.gserviceaccount.com".
  • "group:emailid" — An email address that represents a Google group. For example,"group:admins@example.com".
  • "domain:domain" — A domain name that represents all the users of that domain. For example,"domain:google.com" or"domain:example.com".
  • "projectOwner:projectid" — Owners of the given project. For example,"projectOwner:my-example-project"
  • "projectEditor:projectid" — Editors of the given project. For example,"projectEditor:my-example-project"
  • "projectViewer:projectid" — Viewers of the given project. For example,"projectViewer:my-example-project"
bindings[].conditionobject

A condition object associated with this binding. Each role binding can only contain one condition.

optional
bindings[].condition.titlestring Title of the condition. For example,"expires_end_of_2018".
bindings[].condition.descriptionstring Optional description of the condition. For example,"Expires at midnight on 2018-12-31".optional
bindings[].condition.expressionstringAttribute-based logic expression using a subset of the Common Expression Language (CEL). For example,"request.time < timestamp('2019-01-01T00:00:00Z')".
etagstringHTTP 1.1Entity tag for the policy. writable

For information about status and error codes returned by this API, see thereference page.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.