# GetBucketOwnershipControls

GetBucketOwnershipControls reads a bucket's Object Ownership setting - on Amazon S3, the
switch that decides who owns uploaded objects and whether ACLs apply at all. Buckets on
STRG have no such setting, so the operation checks that the bucket exists and then answers
`404 OwnershipControlsNotFoundError`, the same answer Amazon S3 gives for a bucket without
ownership controls. Tools such as the AWS CLI and Terraform ask for it, and they already know
what that answer means.

**Info: Good to know on STRG**

- The answer is always `404 OwnershipControlsNotFoundError`, never an `OwnershipControls`
  document - and in particular never `BucketOwnerEnforced`, because a bucket's `private` or
  `public-read` ACL is honoured ([GetBucketAcl](https://docs.strg.com/s3-api/GetBucketAcl) reads it).
- PutBucketOwnershipControls and DeleteBucketOwnershipControls are answered with
  `501 NotImplemented`, so a client knows straight away.
- `x-amz-expected-bucket-owner` is welcome and has nothing to check: a key only ever reaches
  buckets of its own account.

## When you'd use it

- **Infrastructure as code.** Terraform asks for a bucket's ownership controls while it reads
  the bucket's current state. The not-found answer tells it there is nothing configured, and
  the plan carries on.
- **Inspecting a bucket from the command line.** Someone checking how a bucket is set up with
  `aws s3api` gets the same answer a bucket without ownership controls gives on Amazon S3.
- **Scripts that check whether ACLs apply.** A script written for Amazon S3 that reads this
  setting before relying on a bucket's ACL learns that no ownership controls are in place - and
  on STRG the bucket's ACL is indeed honoured.

## Request

```http
GET /?ownershipControls 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
```

The path-style form is `GET /my-bucket?ownershipControls` on `s3.eu-central-1.strg.com` -
[Addressing](https://docs.strg.com/s3-api/overview#addressing) explains both.

### Permissions

The access key needs **Read bucket settings** (`buckets:read-config`). Every access key holds
it, whether it covers all buckets or only some - a key scoped to specific buckets reads only
those. [Access keys](https://docs.strg.com/access-keys#always-included) has the details.

### URI parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Bucket` | String | Yes | The bucket whose ownership controls to read. |
| `ownershipControls` | Flag | Yes | Selects this operation. Sent with no value. |

Any other query parameter is answered with `501 NotImplemented`.

### Request headers

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

### Request body

None.

## Response

STRG never answers this operation with `200 OK`. Once the bucket is confirmed, the answer is
`404 Not Found` with the error document below.

### Response headers

| Name | Description |
| --- | --- |
| `Content-Type` | `application/xml`. |
| `x-amz-request-id` | The request ID, handy for a support request. |

### Response body

| Element | Type | Description |
| --- | --- | --- |
| `OwnershipControls` | Container | Never returned. Amazon S3 returns it, holding one `Rule` with an `ObjectOwnership` of `BucketOwnerEnforced`, `BucketOwnerPreferred` or `ObjectWriter`, for a bucket that has ownership controls. |

The error document STRG returns:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Error><Code>OwnershipControlsNotFoundError</Code><Message>The bucket ownership controls were not found</Message><Resource>/</Resource><BucketName>my-bucket</BucketName><RequestId>...</RequestId></Error>
```

## Errors

These are the errors this request can return, and the situation behind each one.

| Code | HTTP status | When |
| --- | --- | --- |
| `OwnershipControlsNotFoundError` | 404 | Always, for a bucket the access key can reach. This is the normal answer. |
| `NoSuchBucket` | 404 | The bucket does not exist, belongs to another account, or is in a region other than the endpoint's - including when the account has nothing stored in the endpoint's region. |
| `AccessDenied` | 403 | The access key is scoped to buckets that do not include this one, the account is not active, or the request is unsigned. |
| `InvalidAccessKeyId` | 403 | The access key does not exist, has expired or been revoked - or it was created moments ago and is not usable in this endpoint's region yet, in which case the same request works shortly afterwards. |
| `SignatureDoesNotMatch` | 403 | The request signature does not match. |
| `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 take. |
| `SlowDown` | 503 | Too many requests. The `Retry-After` header says when a retry is welcome; the AWS SDKs retry on their own. |
| `ServiceUnavailable` | 503 | A temporary failure; the same request can be retried. |
| `InternalError` | 500 | An unexpected failure while confirming the bucket; the same request can be retried. |

## Differences from Amazon S3

The table lists each place where STRG behaves differently, and what that means for a client.

| Aspect | Amazon S3 | STRG |
| --- | --- | --- |
| Object Ownership | Configurable per bucket; new buckets get `BucketOwnerEnforced` | Buckets have no ownership controls, so every bucket answers `404 OwnershipControlsNotFoundError` |
| ACLs | Disabled under `BucketOwnerEnforced` | A bucket is `private` or `public-read`, and that ACL is honoured; [GetBucketAcl](https://docs.strg.com/s3-api/GetBucketAcl) and [PutBucketAcl](https://docs.strg.com/s3-api/PutBucketAcl) read and set it |
| Setting or removing it | PutBucketOwnershipControls, DeleteBucketOwnershipControls | Both answered with `501 NotImplemented` |
| Bucket in another region | `301` redirect with `x-amz-bucket-region` | `404 NoSuchBucket`. A bucket is reached through its own regional endpoint. |
| `x-amz-expected-bucket-owner` | Checked against the bucket owner | Welcome, with nothing to check |

## Examples

Each example reads the ownership controls of `my-bucket` in `eu-central-1` and treats
`OwnershipControlsNotFoundError` as the expected answer.

**AWS CLI**

```bash
aws s3api get-bucket-ownership-controls \
  --bucket my-bucket \
  --endpoint-url https://s3.eu-central-1.strg.com \
  --region eu-central-1
```

The command ends with `An error occurred (OwnershipControlsNotFoundError) when calling the
GetBucketOwnershipControls operation` and a non-zero exit status.

**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_bucket_ownership_controls(Bucket="my-bucket")
    print(response["OwnershipControls"])
except ClientError as error:
    if error.response["Error"]["Code"] == "OwnershipControlsNotFoundError":
        print("no ownership controls")
    else:
        raise
```

**JavaScript (AWS SDK v3)**

```javascript
import { GetBucketOwnershipControlsCommand, 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 GetBucketOwnershipControlsCommand({ Bucket: "my-bucket" }),
  );
  console.log(response.OwnershipControls);
} catch (error) {
  if (error.name === "OwnershipControlsNotFoundError") {
    console.log("no ownership controls");
  } else {
    throw error;
  }
}
```

## Related

- [GetBucketAcl](https://docs.strg.com/s3-api/GetBucketAcl)
- [PutBucketAcl](https://docs.strg.com/s3-api/PutBucketAcl)
- [Access keys](https://docs.strg.com/access-keys)
- [S3 API overview](https://docs.strg.com/s3-api/overview) - including the [other S3 operations](https://docs.strg.com/s3-api/overview#other-s3-operations)