Object Lock: Manage Object-level Retention via S3 API

In addition to bucket-level default retention, you can manage retention settings on individual objects using the S3-compatible API. This allows you to set, extend, or query retention on a per-object basis.

Prerequisites

• The bucket must have Object Lock enabled
• S3-compatible credentials (Access Key + Secret Access Key)

Set retention on an object

Use put-object-retention to set or extend the retention period for an object:

aws s3api put-object-retention \
  --bucket my-compliant-bucket \
  --key my-document.pdf \
  --retention '{"Mode": "COMPLIANCE", "RetainUntilDate": "2025-12-31T00:00:00Z"}' \
  --endpoint-url https://object.storage.eu01.onstackit.cloud

Parameters

Field	Type	Description
Mode	string	COMPLIANCE or GOVERNANCE
RetainUntilDate	ISO 8601 timestamp	Date until the object is protected

Note: In COMPLIANCE mode, the retention period can only be extended, never shortened or removed. In GOVERNANCE mode, the retention can be shortened or removed by including --bypass-governance-retention in the request.

Get retention of an object

aws s3api get-object-retention \
  --bucket my-compliant-bucket \
  --key my-document.pdf \
  --endpoint-url https://object.storage.eu01.onstackit.cloud

Response:

{
  "Retention": {
    "Mode": "COMPLIANCE",
    "RetainUntilDate": "2025-12-31T00:00:00Z"
  }
}

Legal Hold

A Legal Hold prevents an object from being deleted regardless of its retention settings. Unlike retention, a Legal Hold has no expiration date — it remains in effect until explicitly removed.

Enable Legal Hold

aws s3api put-object-legal-hold \
  --bucket my-compliant-bucket \
  --key my-document.pdf \
  --legal-hold '{"Status": "ON"}' \
  --endpoint-url https://object.storage.eu01.onstackit.cloud

Disable Legal Hold

aws s3api put-object-legal-hold \
  --bucket my-compliant-bucket \
  --key my-document.pdf \
  --legal-hold '{"Status": "OFF"}' \
  --endpoint-url https://object.storage.eu01.onstackit.cloud

Check Legal Hold status

aws s3api get-object-legal-hold \
  --bucket my-compliant-bucket \
  --key my-document.pdf \
  --endpoint-url https://object.storage.eu01.onstackit.cloud

Interaction between retention and Legal Hold

An object can have both a retention period and a Legal Hold at the same time. For the object to be deleted, both conditions must be met:

1. The retention period must have expired (or no retention is set)
2. Legal Hold must be OFF (or not set)

Retention active?	Legal Hold active?	Object can be deleted?
No	No	Yes
Yes	No	No (until retention expires)
No	Yes	No (until Legal Hold is removed)
Yes	Yes	No (both must be resolved)