To set or modify the ACLs on an existing bucket you make a PUT request that is
scoped to the bucket and you use the acl
query string parameter.
You must include an XML document in the request body that contains the ACL
settings you want to apply. Notice that you cannot set the ACLs on a new bucket
you are creating. (When you create a new bucket, the default ACL (project-
private) is automatically applied to the bucket.)
You must have FULL_CONTROL
permission to apply ACLs to an existing
bucket. Also, you must be authenticated to use the PUT Bucket method. Anonymous
bucket creation requests will fail.
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 |
See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.
Request headers
Request body elements
The following request body elements are applicable only if you use the
acl
query string parameter to apply ACLs to an existing bucket.
Element | Description |
---|---|
Owner |
Container for bucket owner information. |
ID |
The Google Storage ID of the bucket owner or the Google Storage ID of the user or group for whom the ACLs are being applied. |
Name |
Comment field for GroupByEmail , GroupById , UserByEmail , and UserById . If you do not specify anything in Name when you apply an ACL, the Cloud Storage system populates this field with the email address you specified in EmailAddress . |
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, including READ , WRITE , or FULL_CONTROL |
EmailAddress |
A user account email address or a Google group email address. |
Domain |
A Google Workspace or Cloud Identity domain. |
Request syntax
PUT /?acl HTTP/1.1 Host: BUCKET_NAME.storage.googleapis.com Date: DATE Content-Length: REQUEST_BODY_LENGTH Content-Type: MIME_TYPE_OF_THE_BODY Authorization: AUTHENTICATION_STRING XML_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 named acme-pets
. The ACLs grant
WRITE
permission to members of the Cloud Storage group. Granting
WRITE
permission to the group lets each group member upload objects to the
acme-pets
bucket, delete objects in the acme-pets
bucket, and list objects
in the acme-pets
bucket. The ACLs also grant jane@example.com FULL_CONTROL
of the acme-pets
bucket, which lets Jane upload objects, delete objects, list
objects, and modify ACLs on the acme-pets
bucket.
Request
PUT /?acl HTTP/1.1 Host: acme-pets.storage.googleapis.com Date: Thu, 10 Jun 2010 03:38:42 GMT Content-Length: 705 Authorization: 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="GroupByEmail"> <EmailAddress>gs-discussion@googlegroups.com</EmailAddress> </Scope> <Permission>WRITE</Permission> </Entry> </Entries> </AccessControlList>