Set object ACLs
To change the ACLs on an object you make a PUTrequest that is scoped to the bucket and object and you use theacl query string parameter. You must also include an XML documentin the request body that contains the ACL settings you want to apply.
You can also specify ACLs when you upload an object. To do this you can use thex-goog-acl request header. When you use thex-goog-aclrequest header you can apply one of the predefined ACLs. If youdon't use thex-goog-acl request header when you upload an object,the default ACL (private) is applied to the object.
Keep in mind, a bucket's ACLs determines whether a user has permission toupload objects into the bucket. If a bucket grantsWRITEpermission to anonymous users, then users can upload objects withoutauthenticating. Otherwise, all upload requests must be authenticated and onlythose users withWRITE permission can upload objects into abucket.
You must haveFULL_CONTROL permission to apply ACLs to an existingobject.
x-goog-acl request header in conjunction with theacl query string parameter. You must not include an XML documentwith the request and you must specify a predefined ACL in the request. When youdo this, thex-goog-acl header takes precedence over theacl query string parameter and the predefined ACL is applied tothe object.Query string parameters
| Parameter | Description | Required |
|---|---|---|
acl | Scopes the request to ACL changes only. You can use this only if you are using the PUT Object method to change ACLs on an existing object. You must specify the ACLs in an XML document in the request body. | No |
generation | Specifies the generation to update ACLs for. You can use this only if you are using the PUT Object method to change ACLs on an existing object. You must specify the ACLs in an 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 object.
| Element | Description |
|---|---|
Owner | Container for object owner information. |
ID | The Cloud Storage ID of the object 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
The following syntax applies to PUT Object requests that use theacl query string parameter.
PUT /OBJECT_NAME?acl HTTP/1.1Host:BUCKET_NAME.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPEAuthorization:AUTHENTICATION_STRINGXML_DOCUMENT_DEFINING_ACLS
The following syntax applies to conditional PUT Object requests that use theacl query string parameter as well asgeneration andmetageneration.
PUT /object?acl HTTP/1.1Host: bucket.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPEAuthorization:AUTHENTICATION_STRINGx-goog-if-generation:GENERATION_NUMBERx-goog-if-metageneration:META_GENERATION_NUMBERXML_DOCUMENT_DEFINING_ACLS
The following syntax applies to conditional PUT Object for a history objectthat use theacl query string parameter as well asgeneration andmetageneration.
PUT /object?acl&generation=136088769710500 HTTP/1.1Host: bucket.storage.googleapis.comDate:DATEContent-Length:REQUEST_BODY_LENGTHContent-Type:MIME_TYPEAuthorization:AUTHENTICATION_STRINGx-goog-if-metageneration:META_GENERATION_NUMBERXML_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 thelondon.jpg object, which is stored inthetravel-maps bucket. The ACLs grant jane@example.comFULL_CONTROLpermission, which lets Jane downloadlondon.jpg and change the ACLs onlondon.jpg. The ACLs also grant joe@example.comREAD permission tolondon.jpg, which lets Joe downloadlondon.jpg.
Request
PUT /london.jpg?acl HTTP/1.1Host: travel-maps.storage.googleapis.comDate: Sat, 20 Feb 2010 17:08:44 GMTContent-Length: 682Content-Type=application/xml; charset=UTF-8Authorization: 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>READ</Permission> </Entry> </Entries></AccessControlList>
Response
HTTP/1.1 200 OKDate: Sat, 20 Feb 2010 17:08:45 GMTContent-Length: 0Content-Type: text/html
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.