Create an ACL for an object

Edit online

A PUT issued to an object with the proper parameters creates an access control list (ACL) for that object. Access control lists allow for granting different sets of permissions to different storage accounts using the account’s ID, or by using a pre-made ACL.

ACL grantees can be specified using any of the following methods:

Method	Description	Example
Canonical ID	User account UUID	`43a89ab8-a5e9-44bf-9671-d23a8729b2e0`
Email Address	Username of user account as set in COS Manager	`user1`
URI	Used for pre-defined groups. COS supports the All Users Group for bucket ACLs and the All Users Group and Authenticated Users URIs for Object ACLs. All other predefined groups are unsupported.	`http://acs.amazonaws.com/groups/global/AllUsers` or `http://acs.amazonaws.com/groups/global/AuthenticatedUsers`

The assigned permissions behave as follows:

Permission	When granted on a bucket	When granted on an object
READ	Allows grantee to list and read all objects in bucket	Allows grantee to read object data and metadata
WRITE	Allows grantee to create, overwrite and delete any object in bucket. Cannot be granted independently from READ permission.	N/A
READ_ACP	This permission does not exist for buckets; default setting is FULL_CONTROL	Allows grantee to read object ACL and object legal hold
WRITE_ACP	Default setting is FULL_CONTROL	Allows grantee to write ACL and legal hold for applicable object
FULL_CONTROL	Allows grantee READ, WRITE, READ_ACP and WRITE_ACP permissions on bucket	Allows grantee READ, READ_ACP and WRITE_ACP permissions on object

The following canned ACLs are supported by IBM COS. Values not listed below are not supported.

Canned ACL	Applies to	Notes
private	Bucket and object	When set on a bucket, the requestor is interpreted as the bucket owner.
public-read	Bucket and object	When set on a bucket, the requestor is interpreted as the bucket owner.
public-read-write	Bucket and object	When set on a bucket, the requestor is interpreted as the bucket owner.
authenticated-read	Bucket and object	Supported when set on an object only. Not supported as a bucket ACL.

Syntax


PUT https://{endpoint}/{bucket-name}/{object-name}?acl= # path style
PUT https://{bucket-name}.{endpoint}/{object-name}?acl= # virtual host style

Sample request (canned ACL)


PUT /example-bucket/queen-bee?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T162842Z
x-amz-acl: public-read
Host: 67.228.254.193

Sample response


HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 16:28:42 GMT
X-Clv-Request-Id: b8dea44f-af20-466d-83ec-2a8563f1617b
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: b8dea44f-af20-466d-83ec-2a8563f1617b
Content-Length: 0

Sample request (canned ACL in header)

It is also possible to assign a canned ACL directly when uploading an object by passing the x-amz-acl header and a canned ACL value. This example makes the queen-bee object publicly and anonymously accessible.


PUT /example-bucket/queen-bee HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T162842Z
x-amz-acl: public-read
Host: 67.228.254.193

Sample response


HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 16:28:42 GMT
X-Clv-Request-Id: b8dea44f-af20-466d-83ec-2a8563f1617b
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: b8dea44f-af20-466d-83ec-2a8563f1617b
Content-Length: 0

Sample request (custom ACL)

This is an example of specifying a custom ACL to allow for another account to view the ACL for the “queen-bee” object, but not to access object itself. Additionally, a third account is given full access to the same object as another element of the same ACL.


PUT /example-bucket/queen-bee?acl= HTTP/1.1
Authorization: {authorization-string}
x-amz-date: 20161207T163315Z
Content-Type: text/plain
Host: 67.228.254.193
Content-Length: 564


<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Owner>
    <ID>{owner-storage-account-uuid}</ID>
    <DisplayName>OwnerDisplayName</DisplayName>
  </Owner>
  <AccessControlList>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{first-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee1DisplayName</DisplayName>
      </Grantee>
      <Permission>READ_ACP</Permission>
    </Grant>
    <Grant>
      <Grantee xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CanonicalUser">
        <ID>{second-grantee-storage-account-uuid}</ID>
        <DisplayName>Grantee2DisplayName</DisplayName>
      </Grantee>
      <Permission>FULL_CONTROL</Permission>
    </Grant>
  </AccessControlList>
</AccessControlPolicy>

Sample response


HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 17:11:51 GMT
X-Clv-Request-Id: ef02ea42-6fa6-4cc4-bec4-c59bc3fcc9f7
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: ef02ea42-6fa6-4cc4-bec4-c59bc3fcc9f7
Content-Length: 0