All Products
Search

This Product

    Object Storage Service:PutObjectACL

    Document Center

    Object Storage Service:PutObjectACL

    Last Updated:Jun 04, 2026

    Modifies the access control list (ACL) of an object. Only the bucket owner with read and write permissions on the object can call this operation.

    Versioning

    By default, PutObjectACL configures the ACL of the current version of an object. You can specify a version ID to configure the ACL of a specific version.

    • If the specified version is a delete marker, OSS returns 405 MethodNotAllowed.

    • If no version ID is specified and the latest version is a delete marker, OSS returns 404 NoSuchKey.

    ACL overview

    The PutObjectACL operation sets the x-oss-object-acl header to configure the ACL of an object. The following table describes the valid ACL values.

    ACL

    Description

    private

    Only the object owner has read and write permissions. Other users cannot access the object.

    public-read

    The object owner has read and write permissions. Other users have read-only access.

    public-read-write

    All users have read and write permissions on the object.

    default

    The object inherits the ACL of its bucket.

    Note

    • Object ACLs take precedence over bucket ACLs. For example, a public-read-write object in a private bucket is accessible to all users. If no object ACL is set, the object inherits the bucket ACL.

    • Read operations: GetObject, HeadObject, CopyObject, and UploadPartCopy. CopyObject and UploadPartCopy read the source object. Write operations: PutObject, PostObject, AppendObject, DeleteObject, DeleteMultipleObjects, CompleteMultipartUpload, and CopyObject. CopyObject writes the destination object.

    • You can include the x-oss-object-acl header in write operations to set the object ACL. For example, include x-oss-object-acl in a PutObject request to set the ACL of the uploaded object.

    Permissions

    By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM policies or Bucket Policy.

    API

    Action

    Description

    PutObjectACL

    oss:PutObjectAcl

    Modifies the ACL of an object in a bucket.

    oss:PutObjectVersionAcl

    Modifies the ACL of a specified version of an object.

    Syntax

    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 ACL of the object.

    Valid values:

    • default (default): The object inherits the ACL of its bucket.

    • private: Only the object owner and authorized users have read and write permissions.

    • public-read: The object owner and authorized users have read and write permissions. Other users have read-only access. Exercise caution when you use this ACL.

    • public-read-write: All users have read and write permissions. 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

    The response to a PutObjectACL request contains only common response headers. For more information, see Common response 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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      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: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

      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

    OSS SDKs

    The following OSS SDKs support PutObjectACL:

    ossutil

    For information about the ossutil command that corresponds to the PutObjectACL operation, see put-object-acl.

    Error codes

    Error code

    HTTP status code

    Description

    AccessDenied

    403

    You are not the bucket owner or lack read and write permissions on the object.

    InvalidArgument

    400

    The specified x-oss-object-acl value is invalid.

    FileAlreadyExists

    409

    The target object is a directory in a hierarchical namespace bucket.