GetObjectLockConfiguration

GetObjectLockConfiguration returns a bucket's Object Lock configuration: whether Object Lock is enabled, and the default retention - a mode and a period - that every object uploaded from then on is locked with. A bucket without Object Lock answers 404 ObjectLockConfigurationNotFoundError, which is simply the S3 way of saying "not enabled". PutObjectLockConfiguration is its counterpart for changing the configuration, and Object Lock explains what Object Lock is and how it protects your data.

Good to know on STRG

The access key needs the Read Object Lock settings permission, which takes the place of an IAM or bucket policy.
x-amz-expected-bucket-owner is welcome and has nothing to check: a key only ever reaches buckets of its own account.
A bucket in another region answers 404 NoSuchBucket rather than a redirect, since each bucket answers on its own regional endpoint.

When you'd use it

Compliance checks. A team that keeps financial records or audit logs for a fixed number of years can have a script read each bucket's configuration and confirm that Object Lock is on and the default retention is the one their policy calls for.
Before writing. A backup tool that relies on locked versions as protection against ransomware can read the configuration first and warn when a bucket has no default retention, so new backups would not be locked on their own.
Confirming a change. A deploy script or an agent that has just called PutObjectLockConfiguration can read the configuration back to check that the mode and period are what it meant to set.

Request

GET /?object-lock HTTP/1.1
Host: my-bucket.s3.eu-central-1.strg.com
Authorization: AWS4-HMAC-SHA256 Credential=...
x-amz-date: 20260926T120000Z
x-amz-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Path-style, the same request is GET /my-bucket?object-lock on s3.eu-central-1.strg.com. Addressing describes both styles.

Permissions

The access key needs Read Object Lock settings (bucket-object-lock:read). A key limited to certain buckets can hold it too, and then reaches only those buckets; a key without it answers 403 AccessDenied. Access keys has the details.

URI parameters

Name	Type	Required	Description
`Bucket`	String	Yes	The bucket whose Object Lock configuration is read.
`object-lock`	Flag	Yes	Selects the Object Lock subresource. Sent without a value.

Any other query parameter is answered 501 NotImplemented, so a client knows straight away that it has no effect here.

Request headers

Name	Type	Required	Description
`x-amz-expected-bucket-owner`	String	No	Welcome, and has nothing to check: an access key only ever reaches its own account's buckets.

Request body

None.

Response

A bucket with Object Lock enabled answers 200 OK with the configuration as XML. A bucket without Object Lock answers 404 ObjectLockConfigurationNotFoundError instead.

Response headers

Name	Description
`x-amz-request-id`	The request ID, for support requests.

Response body

The configuration says that Object Lock is on and, where one is set, which default retention applies. Its elements are these.

Element	Type	Description
`ObjectLockConfiguration`	Container	The root element.
`ObjectLockEnabled`	String	Always `Enabled`. Once Object Lock is enabled on a bucket, it stays enabled for good.
`Rule`	Container	The default retention. Absent when the bucket has Object Lock enabled but no default retention.
`Rule` / `DefaultRetention`	Container	The retention applied to every object uploaded without one of its own.
`DefaultRetention` / `Mode`	String	`GOVERNANCE` or `COMPLIANCE`.
`DefaultRetention` / `Days`	Integer	The retention period in days, 1 to 3,000. Present instead of `Years`.
`DefaultRetention` / `Years`	Integer	The retention period in years, 1 to 8. Present instead of `Days`.

With a default retention, the answer looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <ObjectLockEnabled>Enabled</ObjectLockEnabled>
  <Rule>
    <DefaultRetention>
      <Mode>GOVERNANCE</Mode>
      <Days>30</Days>
    </DefaultRetention>
  </Rule>
</ObjectLockConfiguration>

And without one:

<?xml version="1.0" encoding="UTF-8"?>
<ObjectLockConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <ObjectLockEnabled>Enabled</ObjectLockEnabled>
</ObjectLockConfiguration>

A default retention locks only objects uploaded after it was set. Changing or removing it releases nothing that is already locked.

Errors

These are the errors this operation can answer, and the situation behind each.

Code	HTTP status	When
`ObjectLockConfigurationNotFoundError`	404	The bucket does not have Object Lock enabled.
`NoSuchBucket`	404	The bucket does not exist, it is in a region other than the endpoint's, or your account has no storage in this endpoint's region yet.
`AccessDenied`	403	The access key lacks Read Object Lock settings, is limited to buckets that do not include this one, or your account is not active - or the request is unsigned.
`InvalidAccessKeyId`	403	The access key does not exist, has expired or been revoked, or was created so recently that it is not yet usable in this endpoint's region - a moment later it is.
`SignatureDoesNotMatch`	403	The request signature is wrong.
`RequestTimeTooSkewed`	403	The request time is more than 15 minutes from the server's.
`AuthorizationHeaderMalformed`	400	The signature's credential scope names a region other than the endpoint's.
`NotImplemented`	501	The request carries a query parameter this operation does not accept.
`SlowDown`	503	Too many requests at once; a retry after the `Retry-After` interval goes through.
`ServiceUnavailable`	503	A temporary failure; a retry usually succeeds.

Differences from Amazon S3

A few things work a little differently on STRG, each listed here with what it means for your requests.

Aspect	Amazon S3	STRG
Permission	`s3:GetBucketObjectLockConfiguration` in an IAM or bucket policy	Read Object Lock settings on the access key, with no policy to write
Retention period	`Days` or `Years`	`Days` 1 to 3,000 or `Years` 1 to 8
Bucket in another region	`301` redirect with `x-amz-bucket-region`	`404 NoSuchBucket`. Each bucket answers on its own regional endpoint.
`x-amz-expected-bucket-owner`	Checked against the bucket owner	Welcome, with nothing to check: a key only ever reaches buckets of its own account

Examples

Each example reads the Object Lock configuration of my-bucket, treating a bucket without Object Lock as "not enabled".

AWS CLI
Python (boto3)
JavaScript (AWS SDK v3)

aws s3api get-object-lock-configuration \
  --bucket my-bucket \
  --endpoint-url https://s3.eu-central-1.strg.com \
  --region eu-central-1

For a bucket without Object Lock, the command ends with An error occurred (ObjectLockConfigurationNotFoundError).

import boto3
from botocore.exceptions import ClientError

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.eu-central-1.strg.com",
    region_name="eu-central-1",
)

try:
    response = s3.get_object_lock_configuration(Bucket="my-bucket")
except ClientError as error:
    if error.response["Error"]["Code"] == "ObjectLockConfigurationNotFoundError":
        print("Object Lock is not enabled")
    else:
        raise
else:
    configuration = response["ObjectLockConfiguration"]
    print(configuration["ObjectLockEnabled"])
    retention = configuration.get("Rule", {}).get("DefaultRetention")
    print(retention or "no default retention")

import { GetObjectLockConfigurationCommand, S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  endpoint: "https://s3.eu-central-1.strg.com",
  region: "eu-central-1",
});

try {
  const response = await client.send(
    new GetObjectLockConfigurationCommand({ Bucket: "my-bucket" }),
  );
  const configuration = response.ObjectLockConfiguration;
  console.log(configuration.ObjectLockEnabled);
  console.log(configuration.Rule?.DefaultRetention ?? "no default retention");
} catch (error) {
  if (error.name === "ObjectLockConfigurationNotFoundError") {
    console.log("Object Lock is not enabled");
  } else {
    throw error;
  }
}

PutObjectLockConfiguration - enabling Object Lock and setting the default retention
GetObjectRetention and PutObjectRetention - one object's retention
GetObjectLegalHold and PutObjectLegalHold - one object's legal hold
Object Lock
Access keys
S3 API overview

View as Markdown

When you'd use it​

Request​

Permissions​

URI parameters​

Request headers​

Request body​

Response​

Response headers​

Response body​

Errors​

Differences from Amazon S3​

Examples​

Related​