Tenant Cloud Storage Cloud Object Storage API References Setting an ACL for an object

Setting an ACL for an object

Last Updated At: 2025-10-21 09:10:00

Description

The PUT Object acl API is used to configure the ACL table for an Object in a Bucket. You can pass ACL information through the Header: "x-cos-acl", "x-cos-grant-read", "x-cos-grant-full-control", or pass ACL information through the Body in XML format.

Request

Request Example

PUT /<ObjectKey>?acl HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: GMT Date
Authorization: Auth String

Note:

Authorization: Auth String (For details, please refer to the Request Signature document).

Request Header

Common Headers

This request uses common request headers. For details, see Common Request Headers.

Non-common Headers

Name	Description	Type	Required
x-cos-acl	Define the ACL property of the Object, with valid values: private, public-read, default; Default value: default (inherits Bucket permissions). Note: The current access policy entry limit is 1000. If you do not need to control Object ACL, please fill in default or leave this item unset, inheriting Bucket permissions by default.	String	No
x-cos-grant-read	Grants read access to the grantee. Format: x-cos-grant-read: id="[OwnerUin]"	String	No
x-cos-grant-full-control	Grants full permission to the grantee. Format: x-cos-grant-full-control: id="[OwnerUin]"	String	No

Request Body

The response body returns application/xml data. The following contains all the nodes:

<AccessControlPolicy>
  <Owner>
    <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
    <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>qcs::cam::uin/100000000002:uin/100000000002</ID>
        <DisplayName>qcs::cam::uin/100000000002:uin/100000000002</DisplayName>
      </Grantee>
      <Permission>READ</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

The data are as follows:

Node Name (Keyword)	Parent Node	Description	Type	Required
AccessControlPolicy	No	Container for storing the results of the GET Object ACL	Container	Yes

Content of AccessControlPolicy:

Node Name (Keyword)	Parent Node	Description	Type	Required
Owner	AccessControlPolicy	Object Owner Information	Container	Yes
AccessControlList	AccessControlPolicy	Information about the grantee and permissions	Container	Yes

Content of Owner:

Node Name (Keyword)	Parent Node	Description	Type	Required
ID	AccessControlPolicy.Owner	Object Owner ID, Format: qcs::cam::uin/:uin/ If the ID is that of the root account, and have the same value.	String	Yes
DisplayName	AccessControlPolicy.Owner	Object Owner's Name	String	Yes

Content of AccessControlList:

Node Name (Keyword)	Parent Node	Description	Type	Required
Grant	AccessControlPolicy.AccessControlList	Authorization information for a single object. An AccessControlList can have 100 grants.	Container	Yes

Contents of Grant:

Node Name (Keyword)	Parent Node	Description	Type	Required
Grantee	AccessControlPolicy.AccessControlList.Grant	Grantee Information. The type can be RootAccount or Subaccount. When the type is RootAccount, the ID specifies the root account; when the type is Subaccount, the ID specifies the sub-account.	Container	Yes
Permission	AccessControlPolicy.AccessControlList.Grant	Specifies the permissions granted to the grantee, with enum values: READ, FULL_CONTROL.	String	Yes

Contents of Grantee:

Node Name (Keyword)	Parent Node	Description	Type	Required
URI	AccessControlPolicy.AccessControlList.Grant.Grantee	Specifies all users.	String	Yes
ID	AccessControlPolicy.AccessControlList.Grant.Grantee	User ID, formatted as: qcs::cam::uin/:uin/. If it is the root account, and have the same value.	String	Yes
DisplayName	AccessControlPolicy.AccessControlList.Grant.Grantee	User name	String	Yes

Response

Response Headers

Common Response Headers

This response uses common response headers. For details, see Common Response Headers.

Special Response Headers

This request has no special response header information.

Response Body

The response body is empty.

Error Code

The response may contain the following error code information. For common error messages, please refer to the Error Codes document.

Error Code	Description	Status Code
SignatureDoesNotMatch	If this error code is returned, it means the provided signature is incorrect.	403 Forbidden
NoSuchBucket	If this error code is returned, it means the bucket you want to add the rule to is not found.	404 Not Found
MalformedXML	Invalid XML format. Compare it carefully with the RESTful API documentation.	400 Bad Request
InvalidRequest	The request is invalid. If the error description shows "header acl and body acl conflict," it means that ACL parameters cannot be present in both the header and body.	400 Bad Request

Practical Case

Request

PUT /exampleobject?acl HTTP/1.1
Host: <BucketName-APPID>.<Endpoint>
Date: Fri, 25 Feb 2017 04:10:22 GMT
Authorization: q-sign-algorithm=sha1&q-ak=AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&q-sign-time=1484724784;32557620784&q-key-time=1484724784;32557620784&q-header-list=host&q-url-param-list=acl&q-signature=785d9075b8154119e6a075713c1b9e56ff0bddfc
Content-Length: 229
Content-Type: application/x-www-form-urlencoded

<AccessControlPolicy>
  <Owner>
    <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
    <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>qcs::cam::uin/100000000001:uin/100000000001</ID>
        <DisplayName>qcs::cam::uin/100000000001:uin/100000000001</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>qcs::cam::uin/100000000002:uin/100000000002</ID>
        <DisplayName>qcs::cam::uin/100000000002:uin/100000000002</DisplayName>
      </Grantee>
      <Permission>READ</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 0
Connection: keep-alive
Date: Fri, 25 Feb 2017 04:10:22 GMT\

x-cos-request-id: NTg3ZjFjMmJfOWIxZjRlXzZmNDhfMjIw