Set bucket access permissions

Updated at：2025-11-03

API description

This API is designed to configure the access permission of a bucket. Currently, BOS supports two methods for setting ACLs. The first method is to use CannedAcl. During PutBucketAcl, configure the item via the header "x-bce-acl". Current settable permissions include: private, public-read and public-read-write (case-sensitive). The second method is to upload an ACL file. Refer to ACL File Format for the file format.

Notes

BOS does not support setting "x-bce-acl" and uploading ACL files in a single request at the same time.

Only the bucket owner or users with FULL_CONTROL permissions can set the bucket's ACL.

By default, a bucket's permission is set to private when it is created.

Request URI

PUT /v1/{bucketName}/?acl

Parameter name	Parameter type	Required or not	Description	Example value	Parameter location
bucketName	String	Yes	Bucket name	"bucketName_example"	Path

Request header parameters

Parameter name	Parameter type	Required or not	Description	Example value
xBceAcl	String	No	ACL permissions set for the bucket include: private, public-read and public-read-write.	"xBceAcl_example"

Parameters of request body

Description of the data structure of request body fields

Parameter name	Parameter type	Required or not	Description	Example value
accessControlList	List	No	Identify the start of the ACL body, which includes one or more groups of ACL configuration items made up of grant+permission+resource+condition.

Description of AccessControlList field data structure

Parameter name	Parameter type	Required or not	Description	Example value
effect	String	No	Determine whether requests matching this ACL configuration item are permitted. The values can be "Allow" or "Deny". "Allow" means execution is permitted, while "Deny" means execution is denied.	Allow
grantee	List	Yes	Specify the grantee.
permission	List	Yes	Permissions affected by ACL configuration items include READ, LIST, WRITE, and GetObject. For detailed explanations of these permissions, refer to "permissions supported by bucket ACL."
resource	List	No	Resources affected by ACL configuration items, indicating that access permissions are set for resources within the range specified by resource, and wildcards are supported. For example: /or/xxx. If the resource is not filled in or filled with the bucket name, it is equivalent to setting the resource field to [, /_], which means setting access permissions for the bucket and all objects.
notResouce	String	No	Resources affected by ACL configuration specify access permissions for resources outside the range defined by notResource, and wildcards are supported. For example, /or/xxx* means access permissions are set for objects other than ObjectKey in BucketName or objects without the XXX prefix. If the notResource field is left blank, it is treated as not being configured, and access permissions are set for the bucket and all objects by default.
condition	Condition	No	Restrictions contained in ACL configuration items support the configuration of IP address and referer list

Description of Grantee field data structure

Parameter name	Parameter type	Required or not	Description	Example value
id	String	No	Provide the account ID of the grantee. You can find the user's account ID by logging into the console and navigating to User Information - Basic Information under the account name.	10eb6f5ff6ff4605bf044313e8f3ffa5

Description of Condition field data structure

Parameter name	Parameter type	Required or not	Description	Example value
currentTime	CurrentTime	No	Configure time restrictions in the condition section, supporting "dateLessThan," "dateLessThanEquals," "dateGreaterThan," and "dateGreaterThanEquals." Any number of these can be set, but all specified conditions must be satisfied for a match.
secureTransport	Boolean	No	Indicate whether only HTTPS access is allowed. Options are "true" or "false", with "false" as the default. When set to "true," only HTTPS access is allowed.	true
ipAddress	List	No	Identify the ip to which access permission is granted
referer	Referer	No	Identify the referer to which access permission is granted

Description of CurrentTime field data structure

Parameter name	Parameter type	Required or not	Description	Example value
dateLessThan	String	No		2020-07-01T12:00:00Z
dateGreaterThan	String	No		2018-03-01T15:00:00Z

Description of Referer field data structure

Parameter name	Parameter type	Required or not	Description	Example value
stringLike	List	No
stringEquals	List	No

Response body parameters

None

Request example

                JSON
                
            

                PUT /v1/bucketName_example/?acl
 <Common request headers>
x-bce-acl: xBceAcl_example
{
  "accessControlList" : [ {
    "notResouce" : "notResouce",
    "condition" : {
      "currentTime" : {
        "dateLessThan" : "2020-07-01T12:00:00Z",
        "dateGreaterThan" : "2018-03-01T15:00:00Z"
      },
      "secureTransport" : true,
      "referer" : {
        "stringLike" : [ "http://www.abc.com/*" ],
        "stringEquals" : [ "http://www.abc.com" ]
      },
      "ipAddress" : [ "192.168.1.1" ]
    },
    "resource" : [ "bucket1/*" ],
    "effect" : "Allow",
    "grantee" : [ {
      "id" : "10eb6f5ff6ff4605bf044313e8f3ffa5"
    } ],
    "permission" : [ "FULL_CONTROL" ]
  } ]
}
            

Response example

None

Error code

Please refer to the general error codes

Lifecycle

Get Access Permission for a Bucket