Set bucket ACLs
To set or modify the ACLs on an existing bucket you make a PUT request that isscoped to the bucket and you use theacl query string parameter.You must include an XML document in the request body that contains the ACLsettings you want to apply. Notice that you cannot set the ACLs on a new bucketyou are creating. (When you create a new bucket, the default ACL (project-private) is automatically applied to the bucket.)
You must haveFULL_CONTROL permission to apply ACLs to an existingbucket. Also, you must be authenticated to use the PUT Bucket method. Anonymousbucket creation requests will fail.
x-goog-acl request header in conjunction with theacl query string parameter. You must include an XML document withthe request and you must specify a predefined ACL in the request. When you dothis, thex-goog-acl header takes precedence over theacl query string parameter and the predefined ACL is applied tothe bucket.Query string parameters
| Parameter | Description | Required |
|---|---|---|
acl | You use this to change ACLs on an existing bucket. You must provide the ACL XML document in the request body. | No |
Seesigned URL query string parameters for information on the parametersyou include when creating and usingsigned URLs.
Request headers
Request body elements
The following request body elements are applicable only if you use theacl query string parameter to apply ACLs to an existing bucket.
| Element | Description |
|---|---|
Owner | Container for bucket owner information. |
ID | The Cloud Storage ID of the bucket owner or the Cloud Storage ID of the user or group for whom the ACLs are being applied. |
Name | Comment field forGroupByEmail,GroupById,UserByEmail, andUserById. If you don't specify anything inName when you apply an ACL, Cloud Storage populates this field with the email address you specified inEmailAddress. |
AccessControlList | Container for the ACLs you are applying. |
Entries | Container for the ACL entries you are applying. |
Entry | The ACL entry you are applying. |
Scope | The scope to which the ACLs apply. |
Permission | The permission you are granting. Can be any of the Cloud Storage permissions, includingREAD,WRITE, orFULL_CONTROL |
EmailAddress | A user account email address, a service account email address, or a Google group email address. |
Domain | A Google Workspace or Cloud Identity domain. |
Request syntax
PUT /?acl HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPE_OF_THE_BODYAuthorization:AUTHENTICATION_STRINGXML_DOCUMENT_DEFINING_ACLS
Response headers
The request can return a variety of response headers depending on the request headers you use.
Response body elements
The response does not include an XML document in the response body.
Example
The following sample applies ACLs to a bucket namedacme-pets. The ACLs grantWRITE permission to joe@example.com. GrantingWRITE permission lets Joeupload, delete, and list objects in theacme-pets bucket. The ACLs also grantjane@example.comFULL_CONTROL of theacme-pets bucket, which lets Janeupload objects, delete objects, list objects, and modify ACLs on theacme-petsbucket.
Request
PUT /?acl HTTP/1.1Host: acme-pets.storage.googleapis.comDate: Thu, 10 Jun 2010 03:38:42 GMTContent-Length: 705Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg<?xml version="1.0" encoding="UTF-8"?><AccessControlList> <Owner> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name></Name> </Owner> <Entries> <Entry> <Scope type="UserById"> <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID> <Name></Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>jane@example.com</EmailAddress> <Name></Name> </Scope> <Permission>FULL_CONTROL</Permission> </Entry> <Entry> <Scope type="UserByEmail"> <EmailAddress>joe@example.com</EmailAddress> <Name></Name> </Scope> <Permission>WRITE</Permission> </Entry> </Entries></AccessControlList>
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.