Set access permission for an object
Updated at:2025-11-03
API description
This command sets object access permissions. BOS currently offers two methods for configuring ACLs. The first employs Canned ACLs, where permissions are set via the headers "x-bce-acl" or "x-bce-grant-permission" during PutObjectAcl operations. Supported permissions include private and public-read, though both headers cannot coexist within the same request. The second method involves uploading an ACL file. Refer to ACL File Format for details. Supported fields in ACL files are accessControlList, grantee, id, and permission.
Currently, setting Canned ACL and uploading ACL files cannot be done simultaneously in a single request.
Note:
- Only the bucket owner or users with FULL_CONTROL permission are allowed to set an object's ACL.
- When an object is uploaded, its permission is null by default. If no permission is set for the object, meaning the permission remains null, it will inherit the bucket's permission by default.
- In case of a conflict between object permissions and bucket permissions, the object permissions take precedence.
- If archive storage class objects have not been completely restored, or if the archive storage class files were recently uploaded (refer to the restoration duration for specifics), the Object ACL cannot be set.
Request URI
PUT /v1/{bucketName}/{objectKey}?acl
Request header parameters
| Parameter name | Parameter type | Required or not | Description | Example value |
|---|---|---|---|---|
| xBceAcl | String | No | ACL permission set for object, supporting private and public-read | "xBceAcl_example" |
| xBceGrantRead | String | No | Object IDs authorized for reading, supporting multiple IDs separated by commas | "xBceGrantRead_example" |
| xBceGrantFullControl | String | No | Object IDs authorized for control, supporting multiple IDs separated by commas | "xBceGrantFullControl_example" |
Parameters of request body
None
Response body parameters
None
Request example
None
Response example
None
Error code
Please refer to the general error codes
