# 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](https://docs.strg.com/s3-api/PutObjectLockConfiguration)
is its counterpart for changing the configuration, and [Object Lock](https://docs.strg.com/object-locks) explains
what Object Lock is and how it protects your data.

**Info: 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](https://docs.strg.com/s3-api/PutObjectLockConfiguration) can read the configuration back to
  check that the mode and period are what it meant to set.

## Request

```http
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](https://docs.strg.com/s3-api/overview#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](https://docs.strg.com/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
<?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
<?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**

```bash
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)`.

**Python (boto3)**

```python
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")
```

**JavaScript (AWS SDK v3)**

```javascript
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;
  }
}
```

## Related

- [PutObjectLockConfiguration](https://docs.strg.com/s3-api/PutObjectLockConfiguration) - enabling Object Lock and setting the default retention
- [GetObjectRetention](https://docs.strg.com/s3-api/GetObjectRetention) and [PutObjectRetention](https://docs.strg.com/s3-api/PutObjectRetention) - one object's retention
- [GetObjectLegalHold](https://docs.strg.com/s3-api/GetObjectLegalHold) and [PutObjectLegalHold](https://docs.strg.com/s3-api/PutObjectLegalHold) - one object's legal hold
- [Object Lock](https://docs.strg.com/object-locks)
- [Access keys](https://docs.strg.com/access-keys)
- [S3 API overview](https://docs.strg.com/s3-api/overview)