Use PutBucketObjectWormConfiguration to enable an object-level retention policy for a bucket - Object Storage Service

Use PutBucketObjectWormConfiguration to enable an object-level retention policy (ObjectWorm) on a bucket and optionally configure a default retention policy. This action is irreversible: once ObjectWorm is enabled for a bucket, you cannot disable it.

Usage notes

Important

This feature is available by invitation only. To use this feature, contact technical support to request access. This feature is supported only in the following regions: China (Hangzhou), China (Chengdu), China (Shenzhen), China (Guangzhou), China (Qingdao), China (Beijing), China (Hohhot), China (Heyuan), China (Hong Kong), Germany (Frankfurt), Japan (Tokyo), South Korea (Seoul), Singapore, Malaysia (Kuala Lumpur), Indonesia (Jakarta), Philippines (Manila), Thailand (Bangkok), Saudi Arabia (Riyadh), and UAE (Dubai).

This action is irreversible. After you enable an object-level retention policy for a bucket, you cannot disable its ObjectWorm or versioning features.
Before you call this operation, you must enable versioning for the bucket. Otherwise, the operation returns an error.
ObjectWorm is mutually exclusive with a bucket-level retention policy (BucketWorm). If a bucket-level retention policy is already enabled for the bucket, the call fails and returns an error.
Configuring a default retention policy is optional. If you configure a default retention policy, the system automatically applies it to all new objects uploaded to the bucket. The policy does not apply to existing objects. To apply a retention policy to an existing object, call the PutObjectRetention operation.
Enabling ObjectWorm disables support for append uploads.
You must grant users the oss:PutObjectRetention and oss:GetObjectRetention permissions to allow them to manage object retention policies.

Request syntax

PUT /?objectWorm HTTP/1.1
Content-MD5: ContentMD5
Content-Length: ContentLength
Content-Type: application/xml
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Parameter	Type	Required	Example	Description
Content-MD5	String	Yes	B2M2Y8AsgTpgAmY7PhC****	The Base64-encoded MD5 hash of the request body. OSS uses this header to verify data integrity.
Content-Length	Positive integer	Yes	188	The length of the request body in bytes.

Request elements

Parameter	Type	Required	Example	Description
ObjectWormConfiguration	Container	Yes	N/A	A container for the bucket's object-level retention policy configuration. Parent element: None Child elements: ObjectWormEnabled, Rule
ObjectWormEnabled	String	Yes	Enabled	Specifies whether to enable the object-level retention policy. This value must be `Enabled`. Parent element: ObjectWormConfiguration
Rule	Container	No	N/A	A container for the bucket's default object-level retention policy. Parent element: ObjectWormConfiguration Child element: DefaultRetention
DefaultRetention	Container	No	N/A	The container for the default retention policy. Parent element: Rule Child elements: Mode, Days, Years
Mode	String	No	COMPLIANCE	The default retention mode for the object-level retention policy. The valid value is: COMPLIANCE (compliance mode): Within the retention period, no user, including the root user, can delete or overwrite a protected object version. Parent element: DefaultRetention
Days	Positive integer	No	1	The default retention period in days. Valid values: 1 to 36500. You must specify either `Days` or `Years`, but not both. Parent node: DefaultRetention
Years	Positive integer	No	1	The default retention period is specified in years, with a valid range of 1 to 100. You can set a value for either Days or Years, but not both. Parent element: DefaultRetention

Examples

Example 1: Enable ObjectWorm with a default policy

The following example shows how to enable ObjectWorm for a bucket and configure a default retention policy that protects objects in compliance mode for one day.

Sample request

PUT /?objectWorm HTTP/1.1
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 188
Content-Type: application/xml
Content-MD5: B2M2Y8AsgTpgAmY7PhC****
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d****

<?xml version="1.0" encoding="UTF-8"?>
<ObjectWormConfiguration>
  <ObjectWormEnabled>Enabled</ObjectWormEnabled>
  <Rule>
    <DefaultRetention>
      <Mode>COMPLIANCE</Mode>
      <Days>1</Days>
    </DefaultRetention>
  </Rule>
</ObjectWormConfiguration>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 5374A2880232A65C2300****
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 0
Server: AliyunOSS

Example 2: Enable ObjectWorm without a default policy

The following example shows how to enable ObjectWorm for a bucket without configuring a default retention policy. You can later call PutObjectRetention to configure retention policies on individual objects.

Sample request

PUT /?objectWorm HTTP/1.1
Date: Thu, 17 Mar 2026 11:18:32 GMT
Content-Length: 102
Content-Type: application/xml
Content-MD5: C3N3Z9BthUpgBnZ8QiD****
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=****

<?xml version="1.0" encoding="UTF-8"?>
<ObjectWormConfiguration>
  <ObjectWormEnabled>Enabled</ObjectWormEnabled>
</ObjectWormConfiguration>

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 6485B3990232A65C3400****
Date: Thu, 17 Mar 2026 11:20:15 GMT
Content-Length: 0
Server: AliyunOSS

Error codes

Error code	HTTP status code	Description
InvalidBucketState	409	Versioning is not enabled for the bucket, so ObjectWorm cannot be enabled. Enable versioning and try again.
BucketWormAlreadyEnabled	409	A bucket-level retention policy (BucketWorm) is already enabled for the bucket. You cannot enable an object-level retention policy (ObjectWorm) at the same time.