Create and manage Object Lock in Object Storage

Object Lock prevents objects from being deleted or overwritten until a specified retention period has expired. This how-to covers all Object Lock operations: enabling the Compliance Lock, creating a bucket with Object Lock, configuring default retention, and managing retention at the object level.

Prerequisites

• A STACKIT project with Object Storage enabled
• Appropriate project permissions
• S3-compatible credentials (Access Key + Secret Access Key) for object-level operations

Enable the Compliance Lock

The Compliance Lock is the project-level switch that enables S3 Object Lock for all buckets in a STACKIT project. It must be activated before you can create buckets with Object Lock or configure retention policies.

Activate the Compliance Lock

curl -X POST \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/compliance-lock" \
  -H "Authorization: Bearer $TOKEN"

Response (HTTP 201):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "maxRetentionDays": 365
}

Possible errors

Status	Reason
404	Project not found
409	Compliance Lock is already active

Check the Compliance Lock status

curl -X GET \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/compliance-lock" \
  -H "Authorization: Bearer $TOKEN"

Response (HTTP 200):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "maxRetentionDays": 365
}

Returns HTTP 404 if the Compliance Lock is not active.

Disable the Compliance Lock

curl -X DELETE \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/compliance-lock" \
  -H "Authorization: Bearer $TOKEN"

Response (HTTP 200):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "maxRetentionDays": 365
}

Possible errors

Status	Reason
404	Compliance Lock is not active
409	Buckets with Object Lock still exist

The Compliance Lock can only be disabled if no buckets with Object Lock exist in the project. Since Object Lock cannot be removed from an existing bucket, you must delete all Object Lock-enabled buckets before you can disable the Compliance Lock.

Buckets without Object Lock are not affected and do not need to be deleted.

Deletion protection

A project with an active Compliance Lock cannot be deleted. Both the regular project deletion and force-delete endpoints return HTTP 409 Conflict if the Compliance Lock is active.

To delete a project, you must first disable the Compliance Lock.

Create a bucket with Object Lock

Object Lock can only be enabled at the time the bucket is created. It cannot be activated on existing buckets or disabled after creation.

The Compliance Lock must be active before creating a bucket with Object Lock.

Create the bucket

Add the objectLockEnabled=true query parameter when creating a bucket:

curl -X POST \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/bucket/{bucketName}?objectLockEnabled=true" \
  -H "Authorization: Bearer $TOKEN"

Response (HTTP 201):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "bucket": "my-compliant-bucket"
}

Possible errors

Status	Reason
404	Project not found
409	Compliance Lock is not active (must be enabled first)
409	A bucket with this name already exists

What happens next

Once a bucket is created with Object Lock enabled:

1. Versioning is automatically enabled. Object Lock requires bucket versioning. It is turned on automatically and cannot be suspended.
2. You can configure a default retention policy to set an automatic retention period for all uploaded objects. See Configure default retention.
3. You can set per-object retention using the S3-compatible API. See Manage object-level retention.

Important notes

• Object Lock cannot be disabled after bucket creation.
• You can create buckets without Object Lock in a project that has the Compliance Lock enabled. Omit the objectLockEnabled parameter or set it to false.
• A bucket name must be DNS-conformant (3–63 characters).

Configure default retention

A default retention policy automatically applies a retention period to every object uploaded to a bucket. This saves you from having to set retention on each object individually.

The bucket must have been created with Object Lock enabled.

Retention modes

Mode	Behavior
COMPLIANCE	Objects cannot be deleted or overwritten by anyone until the retention period expires. This mode is suitable for regulatory requirements.
GOVERNANCE	Objects are protected, but users with the s3:BypassGovernanceRetention permission can modify or delete them before the retention period expires. Useful for protection against accidental deletion.

Set or update the default retention

curl -X PUT \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/bucket/{bucketName}/default-retention" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "COMPLIANCE",
    "days": 90
  }'

Response (HTTP 200):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "bucket": "my-compliant-bucket",
  "mode": "COMPLIANCE",
  "days": 90
}

Parameters

Field	Type	Required	Description
mode	string	Yes	COMPLIANCE or GOVERNANCE
days	integer	Yes	Retention period in days. Must be greater than 0 and must not exceed 365 days.

Possible errors

Status	Reason
400	days exceeds the maximum retention period of 365 days
404	Project, bucket, or Object Lock not found
409	Compliance Lock is not active on the project

You can change the default retention mode and duration at any time by calling the PUT endpoint again. Changes apply only to objects uploaded after the update.

Get the current default retention

curl -X GET \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/bucket/{bucketName}/default-retention" \
  -H "Authorization: Bearer $TOKEN"

Response (HTTP 200):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "bucket": "my-compliant-bucket",
  "mode": "COMPLIANCE",
  "days": 90
}

Returns HTTP 404 if no default retention is configured, if Object Lock is not enabled on the bucket, or if the bucket does not exist.

Remove the default retention

curl -X DELETE \
  "https://object-storage.api.{region}.stackit.cloud/v1/project/{projectId}/bucket/{bucketName}/default-retention" \
  -H "Authorization: Bearer $TOKEN"

Response (HTTP 200):

{
  "project": "cd5e788d-5b7b-4ab9-a20d-e790205df10b",
  "bucket": "my-compliant-bucket"
}

Removing the default retention only affects future uploads. Objects that already have a retention period keep their existing protection. Object Lock itself remains active on the bucket.

Manage object-level retention with the S3 API

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

The bucket must have Object Lock enabled.

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

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)