tencent cloud

Cloud Object Storage

DocumentationCloud Object StorageSDK DocumentationMini Program SDKCloud Access ManagementAccess Control

Access Control

Download
Focus Mode
Font Size
Last updated: 2026-05-12 11:19:38

Introduction

This document provides an overview of APIs related to Access Control Lists (ACLs) for buckets and objects, along with SDK sample code.
API
Operation Name
Operation Description
Setting a Bucket ACL
Setting the access control list for a specified bucket
Querying the ACL of a Bucket
Querying the access control list for a specified bucket

Bucket ACL

Setting a Bucket ACL

Feature Overview

The PUT Bucket acl API is used to set the Access Control List (ACL) for a specified bucket.

Use Case

Set the bucket to public read:
cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION',  // The region where the bucket resides, for example, ap-beijing, required field
    ACL: 'public-read'
}, function(err, data) {
    console.log(err || data);
});
Grant a user all permissions for a bucket:
cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION',  // The region where the bucket resides, for example, ap-beijing, required field
    GrantFullControl: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000011:uin/100000000011"' // 100000000001 is the uin
}, function(err, data) {
    console.log(err || data);
});
Modify bucket permissions via AccessControlPolicy:
cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION',  // The region where the bucket resides, for example, ap-beijing, required field
    AccessControlPolicy: {
        "Owner": { // AccessControlPolicy must have an owner.
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the Uin of the user to whom the Bucket belongs
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is the Uin
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});

Parameter Description

Parameter Name
Parameter Description
Type
Required
Bucket
The name of the bucket. The naming format is BucketName-APPID. The bucket name entered here must follow this format.
String
Yes
Region
The region where the bucket is located. For the enumeration values, see Regions and Access Domains.
String
Yes
ACL
Defines the Access Control List (ACL) property of the bucket. For the enumeration values, see the Preset ACL section for buckets in the ACL Overview document, such as private and public-read. The default value is private.
String
No
GrantRead
Grants the grantee the permission to read the bucket. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant authorization to a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When you need to grant authorization to a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example, 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantWrite
Grants the grantee the permission to write to the bucket. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant authorization to a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When you need to grant authorization to a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example, 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantReadAcp
Grants the grantee the permission to read the bucket's Access Control List (ACL) and bucket Policy. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant authorization to a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When you need to grant authorization to a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example, 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantWriteAcp
Grants the grantee the permission to write to the bucket's Access Control List (ACL) and bucket Policy. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant authorization to a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When you need to grant authorization to a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example, 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantFullControl
Grants the grantee all permissions to operate the bucket. Format: id="[OwnerUin]". Multiple grantees can be separated by commas (,).
When you need to grant authorization to a sub-account, id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
When you need to grant authorization to a root account, id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
For example, 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
AccessControlPolicy
List of all information for cross-origin resource sharing configuration
Object
No
- Owner
Bucket owner information
Object
No
- - ID
The complete ID of the bucket owner. Format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]. For example, qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is the uin.
String
No
- Grants
List of authorized person information and permission information.
ObjectArray
No
- - Permission
The permission information granted. Options: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL. For details on the enumeration values, see the bucket operations section in the ACL Overview document.
String
No
- - Grantee
Grantee information
Object
No
- - - ID
The complete ID of the grantee. Format: qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]. For example, qcs::cam::uin/100000000001:uin/100000000001, where 100000000001 is the uin.
String
No
- - - DisplayName
The name of the grantee, which is usually filled in as a string identical to the ID.
String
No
- - - URI
Preset user groups. See the preset user groups section in the ACL Overview document. For example, http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers.
String
No

Callback function description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see the Error Codes document.
Object
- statusCode
HTTP status code returned by the request, for example, 200, 403, 404.
Number
- headers
Header returned by the request
Object
data
The object returned when the request is successful, or null if an error occurs in the request
Object
- statusCode
HTTP status code returned by the request, for example, 200, 403, 404.
Number
- headers
Header returned by the request
Object

Querying the ACL of a Bucket

Feature Overview

The GET Bucket acl API is used to query the Access Control List (ACL) of a bucket. The requester of this API must have write ACL permissions for the bucket.

Use Case

cos.getBucketAcl({
    Bucket: 'examplebucket-1250000000', // Enter your own bucket, required field
    Region: 'COS_REGION',  // The region where the bucket resides, for example, ap-beijing, required field
}, function(err, data) {
    console.log(err || data);
});

Response sample:

{
    "GrantFullControl": "",
    "GrantWrite": "",
    "GrantRead": "",
    "GrantReadAcp": "id=\\"qcs::cam::uin/100000000011:uin/100000000011\\"",
    "GrantWriteAcp": "id=\\"qcs::cam::uin/100000000011:uin/100000000011\\"",
    "ACL": "private",
    "Owner": {
        "ID": "qcs::cam::uin/100000000001:uin/100000000001",
        "DisplayName": "qcs::cam::uin/100000000001:uin/100000000001"
    },
    "Grants": [{
        "Grantee": {
            "ID": "qcs::cam::uin/100000000011:uin/100000000011",
            "DisplayName": "qcs::cam::uin/100000000011:uin/100000000011"
        },
        "Permission": "READ"
    }],
    "statusCode": 200,
    "headers": {}
}

Parameter Description

Parameter Name
Parameter Description
Type
Required
Bucket
The name of the bucket. The naming format is BucketName-APPID. The bucket name entered here must follow this format.
String
Yes
Region
The region where the bucket is located. For the enumeration values, see Regions and Access Domains.
String
Yes

Callback function description

function(err, data) { ... }
Parameter Name
Parameter Description
Type
err
The object returned when a request error occurs, including network errors and business errors. It is null if the request is successful. For more details, see the Error Codes document.
Object
- statusCode
HTTP status code returned by the request, for example, 200, 403, 404.
Number
- headers
Header returned by the request
Object
data
The object returned when the request is successful, or null if an error occurs in the request.
Object
- statusCode
HTTP status code returned by the request, for example, 200, 403, 404.
Number
- headers
Header returned by the request
Object
- ACL
Defines the Access Control List (ACL) property of the bucket. For the enumeration values, see the Preset ACL section for buckets in the ACL Overview document, such as private and public-read. The default value is private.
String
- GrantRead
ID information of the grantee with read permission for the bucket
String
- GrantWrite
ID information of the grantee with write permission for the bucket
String
- GrantReadAcp
ID information of the grantee with permission to read the bucket's Access Control List (ACL) and bucket Policy
String
- GrantWriteAcp
ID information of the grantee with permission to write to the bucket's Access Control List (ACL) and bucket Policy
String
- GrantFullControl
ID information of the grantee with full control permission for the bucket
String
- Owner
Bucket owner information
Object
- - DisplayName
Name of the bucket owner
String
- - ID
Complete ID of the bucket owner
Format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
If the account is a root account, <OwnerUin> and <SubUin> have the same value.
String
- Grants
List of authorized person information and permission information.
ObjectArray
- - Permission
Specifies the permission information granted to the grantee. Enumeration values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL.
String
- - Grantee
Grantee information
Object
- - - DisplayName
Grantee name
String
- - - ID
Complete ID of the grantee:
If it is a root account, the format is qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>
or qcs::cam::anyone:anyone (represents all users)
If it is a sub-account, the format is qcs::cam::uin/<OwnerUin>:uin/<SubUin>
String
- - - URI
Preset user groups. See the preset user groups section in the ACL Overview document. For example, http://cam.qcloud.com/groups/global/AllUsers or http://cam.qcloud.com/groups/global/AuthenticatedUsers.
String

Previous Topic: Hotlink ProtectionNext Topic: CRC64 Check

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback