Object Lock: Configure Default Retention

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

Prerequisites

• The project-level Compliance Lock must be active
• The bucket must have been created with Object Lock enabled

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

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"
}

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

Retention modes explained

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.

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