Adding an ACL to a bucket

You use the HTTP PUT method with the acl query parameter to add an ACL to an existing bucket. Adding an ACL to a bucket replaces any existing ACL in its entirety. You cannot modify an existing ACL in place.

To add an ACL to a bucket, you need write ACL permission for the bucket.

To add an ACL to a bucket, you can use either request headers or an ACL request body. You cannot use ACL headers and an ACL request body in the same request.

With ACL headers, you can specify either a canned ACL or individual x-amz-grant- headers. You cannot specify both a canned ACL and an x-amz-grant- header in the same request.

You can use an ACL request body to change the owner of a bucket you own. You cannot use ACL headers to do this. To change the owner of a bucket, you need both write ACL and change owner permission for the bucket.

If you try to add an ACL that specifies a user account that does not exist, HCP returns a 400 (Bad Request) status code and does not add the ACL to the bucket.

Request line

Depending on whether the bucket name is included in the hostname in the S3 compatible request, a request to add an ACL to a bucket has either of these formats:

• With the bucket name included in the hostname:

  PUT /?acl HTTP/1.1

• With the bucket name following the hostname:

  PUT /bucket-name?acl HTTP/1.1

The acl query parameter is not case sensitive.

Required headers

Authorization

Specifies user credentials or requests anonymous access.

Content-Length

Specifies the size, in bytes, of the request body.

This header is required when you’re using an ACL request body to add an ACL to the bucket. If you’re using ACL headers to add the ACL, the Content-Length header is invalid.

Date

Specifies the date and time when the request is being made according to the requester. Normally, this is the current date and time.

The date and time must always be specified using Greenwich Mean Time (GMT).

To specify the date and time, use this format:

DDD, dd MMM yyyy HH:mm:ss (+0000|GMT)

In this format:

DDD

The three-letter abbreviation for the day of the week, with an uppercase first letter (for example, Mon).

dd

The two-digit day of the month.

MMM

The three-letter abbreviation for the month, with an uppercase first letter (for example, Feb).

yyyy

The four-digit year.

HH

The hour on a 24-hour clock.

mm

The number of minutes.

ss

The number of seconds.

For example:

Thu, 23 Mar 2017 14:27:05 +0000

All S3 compatible requests must include either a Date header or an x-amz-date header. If a request includes both headers, HCP uses the date and time in the x-amz-date header.

Host

Specifies the hostname for the request. The host name identifies either a tenant or a bucket.

For a tenant, use this format:

tenant-name.hcp-domain-name

For a bucket, use this format:

bucket-name.tenant-name.hcp-domain-name

x-amz-date

Specifies the date and time at which the request is being made according to the requester. Normally, this is the current date and time.

For the valid values for this header, see the description of the Date header above.

Optional headers

Content-Type

Specifies the Internet media type of the request body. This header is valid only when the ACL is specified in the request body. The only valid values are application/xml and text/xml.

x-amz-acl

Adds a canned ACL to the bucket.

This header is used only to add a canned ACL to a bucket. If you’re using individual x-amz-grant- headers to add the ACL, the x-amz-acl header is invalid.

x-amz-grant-full-control

Grants full control over the bucket to one or more specified grantees.

If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-full-control header is invalid.

x-amz-grant-read

Grants the browse and read data access permissions for the bucket to one or more specified grantees.

If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read header is invalid.

x-amz-grant-read-acp

Grants the read ACL data access permission for the bucket to one or more specified grantees.

If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-read-acp header is invalid.

x-amz-grant-write

Grants the write and delete data access permissions for the bucket to one or more specified grantees.

If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write header is invalid.

x-amz-grant-write-acp

Grants the write ACL data access permission for the bucket to one or more specified grantees.

If you’re using a canned ACL to add an ACL to a bucket, the x-amz-grant-write-acp header is invalid.

Response headers

The list below describes the headers returned in response to a successful request to add an ACL to a bucket.

Content-length

Specifies the size, in bytes, of the response body. In response to a successful request to store an object, the value of this header is always 0 (zero).

Date

The date and time when HCP responded to the request, in Greenwich Mean Time (GMT). The date and time are returned in this format:

DDD dd MMM yyyy HH:mm:ss GMT

For example:

Fri, 18 Sep 2020 14:27:05 GMT

Status codes

The table below describes HTTP status codes that can be returned in response to a request to add an ACL to a bucket.