Introduction

This API is used to set bucket ACLs. Setting bucket ACLs requires WRITE_ACP permission. A bucket ACL can have up to 100 grants. This API operates in an overwriting manner, which means a new bucket ACL overwrites the old one.

You can set a bucket ACL in either way:

Set an ACL in the request body.

Specify permissions in headers.

Specifying permissions in headers

Specify an ACL in either way:

Designate a predefined ACL using the x-tos-acl request header. Predefined ACLs have preconfigured grantees and permissions. Using this header indicates that you cannot use other headers to specify permissions in the request.

Below are the predefined ACLs:

Predefined ACL	Description
private	Sets private permission that rejects access from other accounts.
public-read	Grants read permission to all users.
public-read-write	Grants read and write permissions to all users.
authenticated-read	Grants read permission to authenticated users only.

Use the x-tos-grant-read, x-tos-grant-write, x-tos-grant-read-acp, x-tos-grant-write-acp, and x-tos-grant-full-control headers to explicitly specify access permissions. If you use these headers, you cannot use the x-tos-acl request header to specify a predefined ACL. The header values adhere to the format of type=value, where the type can be one of the following:

id: The value is an account ID.

canned: The value of a predefined group.

Below are the predefined groups:

Predefined group
Description
AllUsers
All users
AuthenticatedUsers
Authenticated users

Request syntax

Request parameters and headers

For common request headers, see Common parameters.

Name	Location	Type	Required	Sample value	Description
acl	Query	String	Yes	-	Identifies a PutBucketACL request.
x-tos-acl	Header	String	No	private	Bucket ACL setting. Valid values: private: Private permission. public-read: Publicly readable. public-read-write: Publicly readable and writable. authenticated-read: Authenticated users have read access.
x-tos-grant-full-control	Header	String	No	id: test-cid	Grants all permissions to specified users.
x-tos-grant-read	Header	String	No	id: test-cid	Grants READ permission to specified users.
x-tos-grant-read-non-list	Header	String	No	id: test-cid	Revoke the permission to list objects and multipart tasks within the bucket. x-tos-grant-read-non-list must be used in conjunction with x-tos-grant-read-acp, meaningless when used alone. When used in conjunction with x-tos-grant-read-acp, it indicates that the grantee is authorized to access bucket metadata, object metadata, and download objects.
x-tos-grant-read-acp	Header	String	No	id: test-cid	Grants READ_ACP permission to specified users.
x-tos-grant-write	Header	String	No	id: test-cid	Grants WRITE permission to specified users.
x-tos-grant-write-acp	Header	String	No	id: test-cid	Grants WRITE_ACP permission to specified users.

Request body elements

Name	Type	Description
Grants	Array	The root node for object access control.
Grantee	Object	The authorized user. Parent node: Grants.
Type	String	The user type. Parent node: Grantee.
Canned	String	Use this property when Type is Group. Valid values: AllUsers: All users. AuthenticatedUsers: Some users that have been authorized based on the account ID. Parent node: Grantee.
ID	String	Use this property to specify the account ID of the authorized user when Type is CanonicalUser. Parent node: Grantee.
Permission	String	The permission type,the value descriptions are as follows: READ：Allow the authorized user to access bucket metadata, object metadata, download objects, list objects within a bucket, and view shard tasks. READ_NON_LIST：Allow authorized users to access bucket metadata, object metadata, and download objects. WRITE：Allow authorized users to create, overwrite, and delete any object in the bucket, initialize multipart tasks, upload parts, merge parts, and cancel multipart tasks. READ_ACP：Allow the authorized party to read the ACL of the bucket. WRITE_ACP：Allow the authorized user to modify or delete the ACL of the bucket. FULL_CONTROL：Allow the grantee to have READ, WRITE, READ_ACP, and WRITE_ACP permissions on the bucket. Parent node: Grants.
Owner	Object	The object owner.
ID	String	The account ID. Parent node: Owner.
BucketAclDelivered	Bool	Whether to enable default object inheritance bucket ACL function, the possible values are as follows: true：Enable object default inheritance of bucket ACL functionality. false：Disable object default inheritance of bucket ACL functionality. The default value is false. tip The Owner and BucketAclDelivered parameters must be set together, otherwise the default object inheritance bucket ACL feature cannot be enabled.

Response headers

The response contains only common headers.

Response body elements

No elements are used.

Sample request 1

Sample request 2

Sample request 3

Sample response

Predefined group	Description
AllUsers	All users
AuthenticatedUsers	Authenticated users

Torch Object Storage