Access Control List (ACL)

Recent Pages

Access Control List (ACL)

Last updated: 2024-02-02 17:35:18

Overview
This document provides an overview of APIs and SDK code samples related to the access control lists (ACLs) for buckets and objects.
Bucket ACL
API
Operation Name
Description
PUT Bucket acl
Setting a bucket ACL
Sets an ACL for a bucket
GET Bucket acl
Querying a bucket ACL
Queries the ACL of a bucket
Object ACL
API
Operation
Description
PUT Object acl
Setting an object ACL
Sets an ACL for an object in a bucket
GET Object acl
Querying an object ACL
Queries the ACL of an object
Bucket ACL
Setting a bucket ACL
Feature description
This API (PUT Bucket acl) is used to set an ACL for a bucket.
Use case
Set a bucket to allow public-read:
cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    ACL: 'public-read'
}, function(err, data) {
    console.log(err || data);
});
Grant a user full permission for a bucket:
cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    GrantFullControl: 'id="qcs::cam::uin/100000000001:uin/100000000001",id="qcs::cam::uin/100000000011:uin/100000000011"' // 100000000001 is uin.
}, function(err, data) {
    console.log(err || data);
});
Modify bucket permission with AccessControlPolicy:
cos.putBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    AccessControlPolicy: {
        "Owner": { // `Owner` is required in `AccessControlPolicy`.
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is UIN
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});
Parameter description
Parameter
Description
Type
Required
Bucket
Bucket name in the format: BucketName-APPID
String
Yes
Region
Bucket region. For the enumerated values, please see Regions and Access Endpoints.
String
Yes
ACL
Defines the access control list (ACL) attribute of the bucket. For the enumerated values, such as private (default) and public-read, please see the Preset ACL section in ACL Overview.
String
No
GrantRead
Grants a user read access in the format: id="[OwnerUin]".
Use a comma (,) to separate multiple users.
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantWrite
Grants a user write access in the format: id="[OwnerUin]".
Use a comma (,) to separate multiple users.
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Examples: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantReadAcp
Grants a user read permission for bucket ACL and policies in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantWriteAcp
Grants a user write permission for bucket ACL and policies in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantFullControl
Grants full permission in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
To authorize a sub-account, use id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>".
To authorize a root account, use id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>".
Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
AccessControlPolicy
A list of all the information about the CORS configuration
Object
No
- Owner
Object representing the bucket owner
Object
No
- - ID
Complete ID of the bucket owner in the format:  qcs::cam::uin/[OwnerUin]:uin/[OwnerUin],<br>such as `qcs::cam::uin/100000000001:uin/100000000001’, where 100000000001 is uin
String
No
- Grants
List of information on the authorized user and granted permissions
ObjectArray
No
- - Permission
Permission granted. Valid values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL. For the enumerated values, please see the Action permissions section in ACL Overview.
String
No
- - Grantee
Authorized user information
Object
No
- - - ID
Complete ID of the grantee in the format of qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]
Example: qcs::cam::uin/100000000001:uin/100000000001 where 100000000001 is the uin
String
No
- - - DisplayName
String representing the username, which is usually the same as the string you enter for ID
String
No
- - - URI
Preset user groups. For more information, see the Identity (Grantee) section in ACL Overview, such as 
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
Description
Type
err
Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, and 404
Number
- headers
Headers returned by the request
Object
data
Object returned when the request is successful. If the request fails, this parameter is left empty.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, and 404
Number
- headers
Headers returned by the request
Object
Querying a bucket ACL
Feature description
This API (GET Bucket acl) is used to query the ACL of a bucket. To call this API, you need to have permission to read the ACL of the bucket.
Use case
cos.getBucketAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
}, function(err, data) {
    console.log(err || data);
});
Sample response
{
    "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
Description
Type
Required
Bucket
Bucket name in the format: BucketName-APPID
String
Yes
Region
Bucket region. For the enumerated values, please see Regions and Access Endpoints.
String
Yes
Callback function description
function(err, data) { ... }
Parameter
Description
Type
err
Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, and 404
Number
- headers
Returns headers
Object
data
Returns data when the request is successful. If the request fails, this is empty.
Object
- statusCode
Returns an HTTP status code, such as 200, 403, and 404
Number
- headers
Headers returned by the request
Object
x-cos-acl
Defines the access control list (ACL) attribute of the bucket. For the enumerated values such as private and public-read, see the Preset ACLs for buckets section in ACL Overview. Default value: private
Enum
- GrantRead
ID information of the user granted read access
String
- GrantWrite
ID information of the user granted write access
String
- GrantReadAcp
ID information of the user granted read access to the ACL and Policies
String
- GrantWriteAcp
ID information of the user granted write access to the ACL and Policies
String
- GrantFullControl
ID information of the user granted full access
String
- Owner
Bucket owner information
Object
- - DisplayName
Bucket owner username
String
- - ID
Bucket owner ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>. 
For root accounts, <OwnerUin> and <SubUin> have the same value.
String
- Grants
List of information on the authorized user and granted permissions
ObjectArray
- - Permission
Specifies the permission granted to the user. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL
String
- - Grantee
Authorized user information
Object
- - - DisplayName
Authorized user’s username
String
- - - ID
User ID of the authorized user 
For root accounts, the format is qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>
or qcs::cam::anyone:anyone representing all users. 
For sub-accounts, the format is qcs::cam::uin/<OwnerUin>:uin/<SubUin>
String
- - - URI
Preset user groups. For more information see the Identity (Grantee) section in ACL Overview, such as 
http://cam.qcloud.com/groups/global/AllUsers or 
http://cam.qcloud.com/groups/global/AuthenticatedUsers
String
Object ACLs
Setting object ACL
Feature description
This API (PUT Object acl) is used to set the ACL of an object in a bucket.
Note: 
The total number of policies associated with bucket ACL, Policy, and CAM under a single root account (i.e., under the same APPID) cannot exceed 1,000. There is no upper limit on the number of object ACL rules. If you do not need access control for an object, do not make any configuration, and the object will inherit the permissions of its bucket.
Use case
cos.putObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    ACL: 'public-read', /*Optional*/
}, function(err, data) {
    console.log(err || data);
});
Grant a user all permissions for an object:
cos.putObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    GrantFullControl: 'id="100000000001"' // 100000000001 is the uin of the root account.
}, function(err, data) {
    console.log(err || data);
});
Grant the user permission to write the object via AccessControlPolicy:
cos.putObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
    AccessControlPolicy: {
        "Owner": { // `Owner` is required in `AccessControlPolicy`.
            "ID": 'qcs::cam::uin/100000000001:uin/100000000001' // 100000000001 is the UIN of the bucket owner
        },
        "Grants": [{
            "Grantee": {
                "ID": "qcs::cam::uin/100000000011:uin/100000000011", // 100000000011 is the UIN of the sub-account of the bucket owner
            },
            "Permission": "WRITE"
        }]
    }
}, function(err, data) {
    console.log(err || data);
});
Parameter description
Parameter
Description
Type
Required
Bucket
Bucket name, formatted as BucketName-APPID
String
Yes
Region
Bucket region. For the enumerated values, please see Regions and Access Endpoints.
String
Yes
Key
Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview
String
Yes
ACL
Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default
Note: If you do not need access control for the object, set default for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.
String
No
GrantRead
Grants a user read permission for an object in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
To authorize a sub-account, useid="qcs::cam::uin/<owneruin>:uin/<subuin>".
To authorize a root account, useid="qcs::cam::uin/<owneruin>:uin/<owneruin>".
Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
GrantFullControl
Grants a user full access in the format: id="[OwnerUin]". You can use commas (,) to separate multiple users.
To authorize a sub-account, useid="qcs::cam::uin/<owneruin>:uin/<subuin>".
To authorize a root account, useid="qcs::cam::uin/<owneruin>:uin/<owneruin>".
Example: 'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'
String
No
AccessControlPolicy
Sets the object's ACL attributes.
Object
No
- Owner
Information about the object owner
Object
No
- - ID
ID of the object owner in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
For root accounts, <OwnerUin> and <SubUin> have the same value.
String
No
- - DisplayName
Name of the object owner
String
No
- Grants
A list of information about the grantee and granted permissions
ObjectArray
No
- - Permission
Permission granted. Enumerated values: READ, WRITE, READ_ACP, WRITE_ACP, FULL_CONTROL
String
No
- - Grantee
Information about the grantee
Object
No
- - - DisplayName
Name of the grantee
String
No
- - - ID
ID of the authorized user in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
For root accounts, <OwnerUin> and <SubUin> have the same value.
String
No
Callback function description
function(err, data) { ... }
Parameter
Description
Type
err
Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, and 404
Number
- headers
Headers returned by the request
Object
data
Object returned when the request is successful. If the request fails, this parameter is left empty.
Object
- statusCode
HTTP status code returned by the request, such as 200, 204, 403, and 404
Number
- headers
Headers returned by the request
Object
Querying object ACL
Feature description
The API is used to query the ACL of an object. Only the owner of the bucket has the permission to use this API.
Use case
cos.getObjectAcl({
    Bucket: 'examplebucket-1250000000',                               /* Required */
    Region: 'COS_REGION',     /* Bucket region. Required */
    Key: 'exampleobject',              /* Required */
}, function(err, data) {
    console.log(err || data);
});
Parameter description
Parameter
Description
Type
Required
Bucket
Bucket name, formatted as BucketName-APPID
String
Yes
Region
Bucket region. For the enumerated values, please see Regions and Access Endpoints.
String
Yes
Key
Object key (object name), the unique ID of an object in a bucket. For more information, please see Object Overview.
String
Yes
Callback function description
function(err, data) { ... }
Parameter
Description
Type
err
Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, and 404
Number
- headers
Headers returned by the request
Object
data
Object returned when the request is successful. If the request fails, this parameter is left empty.
Object
- statusCode
HTTP status code returned by the request, such as 200, 403, and 404
Number
- headers
Headers returned by the request
Object
- ACL
Defines the ACL attribute of the object. For the enumerated values, such as default, private, and public-read, please see the Preset ACL section in ACL Overview. Default value: default
Note: If you do not need access control for the object, set default for this parameter or leave it empty. In this way, the object will inherit the permissions of the bucket it is stored in.
String
- Owner
Owner of the resource
Object
- - ID
Object owner ID in the format of qcs::cam::uin/<OwnerUin>:uin/<SubUin>
For root accounts, <OwnerUin> and <SubUin> have the same value.
String
- - DisplayName
Object owner name
String
- Grants
List of information on the grantee and permissions
ObjectArray
- - Permission
Permission granted. Enumerated values: READ, READ_ACP, WRITE_ACP, FULL_CONTROL
String
- - Grantee
Grantee information
Object
- - - DisplayName
Name of the user
String
- - - ID
User ID in the format: qcs::cam::uin/<OwnerUin>:uin/<SubUin>
For root accounts, <owneruin> and <subuin> have the same value.
String
﻿

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

7x24 Phone Support

tencent cloud

Recent Pages

Access Control List (ACL)

Overview

Bucket ACL

Setting a bucket ACL

Feature description

Use case

Parameter description

Callback function description

Querying a bucket ACL

Feature description

Use case

Sample response

Parameter description

Callback function description

Object ACLs

Setting object ACL

Feature description

Use case

Parameter description

Callback function description

Querying object ACL

Feature description

Use case

Parameter description

Callback function description

Was this page helpful?

Was this page helpful?

API	Operation Name	Description
PUT Bucket acl	Setting a bucket ACL	Sets an ACL for a bucket
GET Bucket acl	Querying a bucket ACL	Queries the ACL of a bucket

API	Operation	Description
PUT Object acl	Setting an object ACL	Sets an ACL for an object in a bucket
GET Object acl	Querying an object ACL	Queries the ACL of an object

Parameter	Description	Type	Required
Bucket	Bucket name in the format: `BucketName-APPID`	String	Yes
Region	Bucket region. For the enumerated values, please see Regions and Access Endpoints.	String	Yes
ACL	Defines the access control list (ACL) attribute of the bucket. For the enumerated values, such as `private` (default) and `public-read`, please see the Preset ACL section in ACL Overview.	String	No
GrantRead	Grants a user read access in the format: id="[OwnerUin]". Use a comma (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"`. To authorize a root account, use `id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"`.Examples: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantWrite	Grants a user write access in the format: id="[OwnerUin]". Use a comma (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"`. To authorize a root account, use `id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"`. Examples: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantReadAcp	Grants a user read permission for bucket ACL and policies in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"`. To authorize a root account, use `id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantWriteAcp	Grants a user write permission for bucket ACL and policies in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"`. To authorize a root account, use `id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
GrantFullControl	Grants full permission in the format: `id="[OwnerUin]"`. You can use commas (,) to separate multiple users. To authorize a sub-account, use `id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"`. To authorize a root account, use `id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"`. Example: `'id="qcs::cam::uin/100000000001:uin/100000000001", id="qcs::cam::uin/100000000001:uin/100000000011"'`	String	No
AccessControlPolicy	A list of all the information about the CORS configuration	Object	No
- Owner	Object representing the bucket owner	Object	No
- - ID	Complete ID of the bucket owner in the format: `qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]`,<br>such as `qcs::cam::uin/100000000001:uin/100000000001’, where 100000000001 is uin	String	No
- Grants	List of information on the authorized user and granted permissions	ObjectArray	No
- - Permission	Permission granted. Valid values: `READ`, `WRITE`, `READ_ACP`, `WRITE_ACP`, `FULL_CONTROL`. For the enumerated values, please see the Action permissions section in ACL Overview.	String	No
- - Grantee	Authorized user information	Object	No
- - - ID	Complete ID of the grantee in the format of `qcs::cam::uin/[OwnerUin]:uin/[OwnerUin]` Example: `qcs::cam::uin/100000000001:uin/100000000001` where 100000000001 is the uin	String	No
- - - DisplayName	String representing the username, which is usually the same as the string you enter for `ID`	String	No
- - - URI	Preset user groups. For more information, see the `Identity (Grantee)` section in ACL Overview, such as `http://cam.qcloud.com/groups/global/AllUsers` or `http://cam.qcloud.com/groups/global/AuthenticatedUsers`	String	No

Parameter Name	Description	Type
err	Object returned when an error (network error or service error) occurs. If the request is successful, this parameter is left empty. For more information, please see Error Codes.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object
data	Object returned when the request is successful. If the request fails, this parameter is left empty.	Object
- statusCode	HTTP status code returned by the request, such as 200, 403, and 404	Number
- headers	Headers returned by the request	Object

tencent cloud

Sign Up

Log in

Recent Pages

Access Control List (ACL)

Overview

Bucket ACL

Setting a bucket ACL

Feature description

Use case

Parameter description

Callback function description

Querying a bucket ACL

Feature description

Use case

Sample response

Parameter description

Callback function description

Object ACLs

Setting object ACL

Feature description

Use case

Parameter description

Callback function description

Querying object ACL

Feature description

Use case

Parameter description

Callback function description

Was this page helpful?

Was this page helpful?