Managing Object Locking via S3 Client Requests

  • Updated on Jan 30, 2026
  • Published on Jan 28, 2026
  • 2 minute(s) read
Prev Next

You can send requests by S3 API to do the tasks described below for configuring and viewing object locking configurations on buckets and objects.  

Bucket Operations

You can manage object lock configuration on buckets using the following API requests and headers. The operations require user permissions which must be granted through identity policies.

Task

S3 API Operation

S3 Permission Required

Enable object locking on a new bucket.

Caution

When you enable object locking on a bucket, object versioning is automatically enabled on the bucket as well.

Include the x-amz-bucket-object-lock-enabled header in the CreateBucket request.

Caution

Once you enable object locking on a bucket, you cannot disable it or suspend versioning for that bucket.

s3:PutBucketObjectLockConfiguration

Enable object locking on an existing bucket and set a default retention period

PutObjectLockConfiguration

s3:PutBucketObjectLockConfiguration

Get the Object Lock configuration of a bucket

GetObjectLockConfiguration

s3:GetObjectLockConfiguration

Object Operations

Task

S3 API Operations

Notes

S3 Permission Required

Retention Period Tasks

Set a retention configuration on an object.

PutObjectRetention

This includes setting the retention mode and setting an explicit retention period on the object. The explicit retention period overrides a default retention period set on the bucket.

s3:PutObjectRetention

Extend a retention period after setting a retention configuration on an object version.

To do this, submit a new lock request for the object version with a Retain Until Date that is later than the one currently configured for the object version.

s3:PutObjectRetention

Get the retention settings of an object.

GetObjectRetention

This includes the date and time and the retention mode.

s3:GetObjectRetention

Get the date and time when an object's lock is due to expire, along with other object information.

GetObject, HeadObject

The response includes the x-amz-object-lock-retain-until-date header if the user has the required permission to view it. This header indicates the date and time that the object's lock is due to expire, if applicable.

s3:GetObjectRetention

Get an object's retention mode, along with other object information.

GetObject, HeadObject

The response includes the x-amz-object-lock-mode header if the user has the required permission to view it. This header indicates the object's lock mode, if applicable.

Compliance mode is not supported. Therefore, object lock mode is always governance if applicable.

s3:GetObjectRetention

Legal Hold Tasks

Apply a legal hold configuration to an object.

PutObjectLegalHold

Placing a legal hold on an object version doesn't affect the retention mode or retention period for that object version.

s3:PutObjectLegalHold

Get an object's current legal hold status.

GetObjectLegalHold, GetObject

The GetObjectLegalHold response indicates whether the specified object has a legal hold in place.

With GetObject, the indication is returned in the x-amz-object-lock-legal-hold response header which is returned if the user has the required permission.

s3:GetObjectLegalHold

Operations that Require Bypassing Governance Mode

Overwrite or delete an object version or alter its lock settings, including shortening the retention period, and removing an object lock by placing a new lock with empty parameters.

You must explicitly include x-amz-bypass-governance-retention:true as a request header with any request that requires overriding governance mode.

s3:BypassGovernanceRetention

Related articles