Modifies the access control list (ACL) of an object. - Object Storage Service

You can call this operation to modify the access control list (ACL) of an object. Only the bucket owner that has permissions to read and write objects in the bucket can call this operation to modify object ACLs.

Versioning

By default, the PutObjectACL operation is called to configure the ACL of the current version of an object. You can specify a version ID in the request to configure the ACL of the specified version of an object.

If you specify a version ID in the request and the version of the associated object is a delete marker, OSS returns the 405 MethodNotAllowed error.
If you do not specify a version ID in the request and the latest version of the associated object is a delete marker, OSS returns the 404 NoSuchKey error.

ACL overview

When you call the PutObjectACL operation, you can set the x-oss-object-acl header in the request to configure the ACL of an object. The following table describes the ACLs that you can configure for an object.

ACL	Description
private	The object is a private resource. Only the owner of the object has permissions to read and write the object. Other users cannot access the object.
public-read	The object is a public-read resource. Only the owner of the object has permissions to read and write this object. Other users can only read the object.
public-read-write	The object is a public-read-write resource. All users have permissions to read and write the object.
default	The ACL of the object is the same as that of the bucket in which the object is stored.

Note

The ACL of an object takes precedence over the ACL of the bucket in which the object is stored. For example, if an object whose ACL is public-read-write is stored in a bucket whose ACL is private, all users can read and write the object. By default, if you do not configure the ACL of an object, the ACL of the object is the same as the ACL of the bucket in which the object is stored.
Operations that read objects include GetObject, HeadObject, CopyObject, and UploadPartCopy, in which CopyObject and UploadPartCopy read the source object. Operations that write objects include PutObject, PostObject, AppendObject, DeleteObject, DeleteMultipleObjects, CompleteMultipartUpload, and CopyObject, in which CopyObject writes the destination object.
When you call operations to write an object, you can also include the x-oss-object-acl header in the request to configure the ACL of the object. For example, you can include the x-oss-object-acl header in a PutObject request to configure the ACL of the object to upload.

Request structure

PUT /ObjectName?acl HTTP/1.1
x-oss-object-acl: Permission
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Header

Type

Required

Example

Description

x-oss-object-acl

String

Yes

public-read

The access control list (ACL) of the object.

Valid values:

default (default): The ACL of the object is the same as that of the bucket in which the object is stored.
private: The ACL of the object is private. Only the owner of the object and authorized users have the read and write permissions on the object.
public-read: The ACL of the object is public-read. Only the owner of the object and authorized users have the read and write permissions on the object. Other users have only the read permissions on the object. Exercise caution when you use this ACL.
public-read-write: The ACL of the object is public-read-write. All users have the read and write permissions on the object. Exercise caution when you use this ACL.

For more information, see Object ACLs.

For more information about the common request headers in a PutObjectACL request, such as Host and Date, see Common request headers.

Response headers

This request contains only common response headers. For more information, see Common HTTP headers.

Examples

Modify the ACL of an object in an unversioned bucket

Sample request

PUT /test-object?acl HTTP/1.1
x-oss-object-acl: public-read
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 29 Apr 2015 05:21:12 GMT
Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:KU5h8YMUC78M30dXqf3JxrTZ****

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
Date: Wed, 29 Apr 2015 05:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

Modify the ACL of an object in a versioned bucket

Sample request

PUT /example?acl&versionId=CAEQMhiBgIC3rpSD0BYiIDBjYTk5MmIzN2JlNjQxZTFiNGIzM2E3OTliODA0**** HTTP/1.1
x-oss-object-acl: public-read
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 06:30:11 GMT
Authorization: OSS qctg2ns3l8u51iu:UTsv3F7L34v+ECq52vURdCSv****

Sample response

HTTP/1.1 200 OK
x-oss-version-id: CAEQMhiBgIC3rpSD0BYiIDBjYTk5MmIzN2JlNjQxZTFiNGIzM2E3OTliODA0****
x-oss-request-id: 5CAC3BF3B7AEADE017000624
Date: Tue, 09 Apr 2019 06:30:11 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

SDK

You can use OSS SDKs for the following programming languages to call the PutObjectACLoperation:

Error codes

Error code	HTTP status code	Description
AccessDenied	403	You are not the bucket owner or do not have permissions to read and write the object whose ACL you want to modify.
InvalidArgument	400	The specified x-oss-object-acl value is invalid.
FileAlreadyExists	409	The object whose ACL you want to modify is a directory in a bucket for which the hierarchical namespace feature is enabled.