PutBucketAcl - Set bucket ACL - Object Storage Service - Alibaba Cloud Documentation Center

Usage notes

When you call the PutBucketAcl operation, note the following items:

You must have write permissions on the bucket.
PutBucketAcl uses overwrite semantics. The new ACL replaces the existing one.
If the specified bucket does not exist, a new bucket is created.

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.

Request structure

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

Request headers

Header

Type

Required

Sample value

Description

x-oss-acl

String

Yes

private

The ACL to set for the bucket.

If this header is omitted, the ACL settings do not take effect.

Valid values: public-read-write, public-read, and private

public-read-write: All users, including anonymous users, can read and write objects in the bucket. Use with caution.
public-read: Only the bucket owner or authorized users can write objects. Other users, including anonymous users, can only read objects. Use with caution.
private: Only the bucket owner or authorized users can read and write objects. Other users, including anonymous users, cannot access objects without authorization.

For the common request headers included in PutBucketAcl requests, see Common request headers.

Response headers

The response to a PutBucketAcl request contains only common response headers. For more information, see Common response headers.

Examples

Sample request

PUT /? acl HTTP/1.1
x-oss-acl: public-read
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Thu, 17 Apr 2025 03:21:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

Sample success response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Fri, 24 Feb 2012 03:21:12 GMT
Content-Length: 0
Connection: keep-alive
Server: AliyunOSS

Sample response for invalid ACL settings

HTTP/1.1 400 Bad Request
x-oss-request-id: 56594298207FB3044385****
Date: Fri, 24 Feb 2012 03:55:00 GMT
Content-Length: 309
Content-Type: text/xml; charset=UTF-8
Connection: keep-alive
Server: AliyunOSS

<? xml version="1.0" encoding="UTF-8"? >
<Error>
  <Code>InvalidArgument</Code>
  <Message>no such bucket access control exists</Message>
  <RequestId>5***9</RequestId>
  <HostId>***-test.example.com</HostId>
  <ArgumentName>x-oss-acl</ArgumentName>
  <ArgumentValue>error-acl</ArgumentValue>
</Error>

OSS SDKs

Call PutBucketAcl with the following OSS SDKs:

ossutil

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

Error codes

Error code	HTTP status code	Description
AccessDenied	403	User authentication information is missing from the request. You do not have permissions to perform this operation.

API	Action	Description
PutBucketAcl	oss:PutBucketAcl	Configures or modifies the ACL of a bucket.