diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst
index f5fef1a5b..c03859423 100644
--- a/doc/source/api/index.rst
+++ b/doc/source/api/index.rst
@@ -10,6 +10,7 @@ Quick Start
 
    ./quickstart/secrets
    ./quickstart/containers
+   ./quickstart/acls
 
 
 API Reference
@@ -20,3 +21,4 @@ API Reference
 
     ./reference/secrets
     ./reference/containers
+    ./reference/acls
diff --git a/doc/source/api/quickstart/acls.rst b/doc/source/api/quickstart/acls.rst
new file mode 100644
index 000000000..53022a967
--- /dev/null
+++ b/doc/source/api/quickstart/acls.rst
@@ -0,0 +1,352 @@
+*************************
+ACL API - Quick Start
+*************************
+
+By default Barbican manages access to its resources (secrets, containers) on a per project
+level, whereby a user is allowed access to project resources based on the roles a user has
+in that project.
+
+Some Barbican use cases prefer a more fine-grained access control for secrets and containers,
+such as at the user level. The Access Control List (ACL) feature supports this more restrictive
+access.
+
+This guide will assume you will be using a local running development environment of Barbican.
+If you need assistance with getting set up, please reference the :doc:`development guide </setup/dev>`.
+
+.. warning::
+
+    This ACL documentation is work in progress and may change in near future.
+
+
+ACL Definition
+##############
+
+ACL defines a set of attributes which are used in policy-based authorization to determine
+access to a target resource. ACL definition is operation specific and is defined per
+secret or per container.
+
+Currently only the 'read' operation is defined. This supports allowing users on the ACL for a
+secret to retrieve its metadata or to decrypt its payload. This also allows users on the ACL
+for a container to retrieve its list of secret references.
+
+ACL allow a secret or a container to be marked private. Private secret/container means that only
+the user who created the secret/container can extract secret. Users with necessary roles on a
+secret/container project will not have access. To allow access to other users, their user ids
+need to be added in related ACL users list.
+
+An operation specific ACL definition has following attribute:
+  * `users`: Whitelist of users who are allowed access to target resource. In this case a user means
+    a Keystone user id.
+  * `creator-only`: Flag to mark a secret or a container private for an operation. Pass `true` to
+    mark private.
+
+To acommplish above mentioned behavior for a secret/container resource, having ACL data populated
+alone is not sufficient.
+
+Following ACL rules are defined and used as `OR` in resource access policy:
+  * ACL based access is allowed when token user is present in secret/container operation specific
+    ACL user list e.g. token user present in `read` users list.
+  * When secret/container resource is marked private, then project-level RBAC users access is not
+    allowed.
+
+.. note::
+
+    Currently Barbican default policy just makes use of `read` ACL data only. So only **GET**
+    calls for a secret and a container resource will make use of ACL data. Other request methods on
+    secret and container resource still uses project level RBAC checks in policy.
+
+As per default policy rules, a user with `admin` role in a secret/container project or a user who
+has created the secret/container can manage ACL for that secret/container.
+
+.. _default_implicit_acl:
+
+Default ACL
+-----------
+
+By default when no ACL is explicitly set on a secret or a container, then clients with necessary
+roles on secret's project or container's project can access it. This default access pattern translates
+to `creator-only` as False and no `users` in ACL settings. That's why every secret and container by
+default has following implicit ACL.
+
+.. code-block:: json
+    
+    {
+      "read":{
+        "creator-only": false
+      }
+    }
+
+
+Above default ACL is also returned on **GET** on secret/container **acl** resource when no
+explicit ACL is set on it.
+
+
+.. _set_acl:
+
+How to Set/Replace ACL
+######################
+
+The ACL for an existing secret or container can be modified via a **PUT** to the **acl** resource.
+This update completely replaces existing ACL settings for this secret or container.
+
+
+To set/replace an ACL for a secret:
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X PUT -H 'content-type:application/json' \
+    -H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
+    -d '
+    {
+      "read":{
+        "users":[
+          "2d0ee7c681cc4549b6d76769c320d91f",
+          "721e27b8505b499e8ab3b38154705b9e",
+          "c1d20e4b7e7d4917aee6f0832152269b"
+        ],
+        "creator-only":true
+      }
+    }' \
+    http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl
+
+    Response (includes secret ACL reference):
+
+    HTTP/1.1 201 Created
+    {"acl_ref": "http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl"}
+
+
+To set/replace an ACL for a container:
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X PUT -H 'content-type:application/json' \
+    -H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
+    -d '
+    {
+      "read":{
+        "users":[
+          "2d0ee7c681cc4549b6d76769c320d91f",
+          "721e27b8505b499e8ab3b38154705b9e",
+          "c1d20e4b7e7d4917aee6f0832152269b"
+        ],
+        "creator-only":true
+      }
+    }' \
+    http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
+
+    Response (includes container ACL reference):
+
+    HTTP/1.1 201 Created
+    {"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
+
+To get more details on the create API you can reference the :ref:`Set Secret ACL <put_secret_acl>`
+or :ref:`Set Container ACL <put_container_acl>` documentation.
+
+
+.. _update_acl:
+
+How to Update ACL
+#################
+
+Existing ACL can be updated via **PUT** or **PATCH** methods on a given secret/container.
+**PUT** interaction replaces existing ACL with provided ACL data whereas **PATCH**
+interaction applies the provided changes on existing ACL of a secret or a container.
+
+To replace an existing ACL for a container:
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X PUT -H 'content-type:application/json' \
+    -H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
+    -d '
+    {
+      "read":{
+        "users":[
+          "2d0ee7c681cc4549b6d76769c320d91f",
+          "721e27b8505b499e8ab3b38154705b9e"
+        ],
+        "creator-only":false
+      }
+    }' \
+     http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
+
+    Response (includes container ACL reference):
+
+    HTTP/1.1 200 OK
+    {"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
+
+
+To remove all users from an existing ACL for a container (pass empty list in `users`):
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X PUT -H 'content-type:application/json' \
+    -H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
+    -d '
+    {
+      "read":{
+        "users":[],
+        "creator-only":false
+      }
+    }' \
+     http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
+
+    Response (includes container ACL reference):
+
+    HTTP/1.1 200 OK
+    {"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
+
+
+To update only the creator-only flag for container ACL (use PATCH):
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X PATCH -H 'content-type:application/json' \
+    -H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
+    -d '
+    {
+      "read":{
+        "creator-only":true
+      }
+    }' \
+     http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {"acl_ref": "http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl"}
+
+
+To update only the users list for secret ACL (use PATCH):
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X PATCH -H 'content-type:application/json' \
+    -H 'X-Auth-Token:e1f540bc6def456dbb0f8c11f21a74ae' \
+    -d '
+    {
+      "read":{
+        "users":[
+          "2d0ee7c681cc4549b6d76769c320d91f",
+          "c1d20e4b7e7d4917aee6f0832152269b"
+        ],
+      }
+    }' \
+     http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {"acl_ref": "http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl"}
+
+
+
+Container and Secret ACL(s) update operation are similar except `containers` resource is used
+instead of the `secrets` resource in URI. To get more details on ACL update APIs, you can reference
+the :ref:`Update Secret ACL <put_secret_acl>` , :ref:`Update Container ACL <put_container_acl>`
+, :ref:`Partial Update Secret ACL <patch_secret_acl>` or :ref:`Partial Update Container ACL
+<patch_container_acl>` documentation.
+
+
+.. _retrieve_acl:
+
+How to Retrieve ACL
+###################
+
+The ACL defined for a secret or container can be retrieved by using a **GET** operation on
+respective **acl** resource.
+The returned response contains ACL data.
+
+To get secret ACL data:
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X GET -H 'X-Auth-Token:b44636bff48c41bbb80f459df69c11aa' \
+    http://localhost:9311/v1/secrets/15621a1b-efdf-41d8-92dc-356cec8e9da9/acl
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {
+      "read":{
+        "updated":"2015-05-12T20:08:47.644264",
+        "created":"2015-05-12T19:23:44.019168",
+        "users":[
+          "c1d20e4b7e7d4917aee6f0832152269b",
+          "2d0ee7c681cc4549b6d76769c320d91f"
+        ],
+        "creator-only":true
+      }
+    }
+
+
+To get container ACL data:
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X GET -H 'X-Auth-Token:b44636bff48c41bbb80f459df69c11aa' \
+    http://localhost:9311/v1/containers/8c077991-d524-4e15-8eaf-bc0c3bb225f2/acl
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {
+      "read":{
+        "updated":"2015-05-12T20:05:17.214948",
+        "created":"2015-05-12T19:47:20.018657",
+        "users":[
+          "721e27b8505b499e8ab3b38154705b9e",
+          "c1d20e4b7e7d4917aee6f0832152269b",
+          "2d0ee7c681cc4549b6d76769c320d91f"
+        ],
+        "creator-only":true
+      }
+    }
+
+
+To get more details on ACL lookup APIs you can reference the :ref:`Get Secret ACL <get_secret_acl>` ,
+:ref:`Get Container ACL <get_container_acl>` documentation.
+
+
+.. _delete_acl:
+
+How to Delete ACL
+#################
+
+ACL defined for a secret or a container can be deleted by using the **DELETE** operation on their respective `acl`
+resource. There is no response content returned on successful deletion.
+
+Delete operation removes existing ACL on a secret or a container if there. It can be treated as resetting a secret
+or a container to :ref:`Default ACL<default_implicit_acl>` setting. That's why invoking delete multiple times on
+this resource will not result in error.
+
+.. code-block:: bash
+
+    Request:
+
+    curl -X DELETE -H 'X-Auth-Token:b06183778aa64b17beb6215e60686a60' \
+    http://localhost:9311/v1/secrets/50f5ed8e-004e-433a-939c-fa73c7fc81fd/acl
+
+    Response:
+
+    200 OK
+
+
+To get more details on ACL delete APIs, you can reference the :ref:`Delete Secret ACL <delete_secret_acl>` ,
+:ref:`Delete Container ACL <delete_container_acl>` documentation.
diff --git a/doc/source/api/reference/acls.rst b/doc/source/api/reference/acls.rst
new file mode 100644
index 000000000..75c02558b
--- /dev/null
+++ b/doc/source/api/reference/acls.rst
@@ -0,0 +1,670 @@
+***********************
+ACL API - Reference
+***********************
+
+.. note::
+
+    This feature is applicable only when Barbican is used in an authenticated
+    pipeline i.e. integrated with Keystone.
+
+.. note::
+
+    Currently the access control list (ACL) settings defined for a container
+    are not propagated down to associated secrets.
+
+.. warning::
+
+    This ACL documentation is work in progress and may change in near future.
+
+
+Secret ACL API
+===============
+
+.. _get_secret_acl:
+
+GET /v1/secrets/{uuid}/acl
+##########################
+Retrieve the ACL settings for a given secret.
+
+If no ACL is defined for that secret, then :ref:`Default ACL<default_implicit_acl>` is returned.
+
+Request/Response (With ACL defined):
+************************************
+
+.. code-block:: none
+
+    Request:
+
+    GET /v1/secrets/{uuid}/acl
+    Headers:
+        X-Auth-Token: {token_id}
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {
+      "read":{
+        "updated":"2015-05-12T20:08:47.644264",
+        "created":"2015-05-12T19:23:44.019168",
+        "users":[
+          {user_id1},
+          {user_id2},
+          .....
+        ],
+        "creator-only":{creator-only-flag}
+      }
+    }
+
+
+Request/Response (With no ACL defined):
+***************************************
+
+.. code-block:: none
+
+    Request:
+
+    GET /v1/secrets/{uuid}/acl
+    Headers:
+        X-Auth-Token: {token_id}
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {
+      "read":{
+        "creator-only": false
+      }
+    }
+
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successful request.                                                         |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Secret not found for the given UUID.                                        |
++------+-----------------------------------------------------------------------------+
+
+.. _put_secret_acl:
+
+PUT /v1/secrets/{uuid}/acl
+##########################
+Create new or replaces existing ACL for a given secret.
+
+This call is used to add new ACL for a secret. If the ACL is already set on a secret, this
+method will replace it with the requested ACL settings. In case of create (first new explicit
+ACL) or replace existing ACL, 200 is returned in both cases. To delete existing users from
+an ACL definition, pass empty list [] for `users`.
+
+Returns an ACL reference in success case.
+
+Attributes
+**********
+
+The ACL resource detailed in this page allows access to individual secrets to be controlled.
+This access is configured via operations on those secrets. Currently only the 'read' operation
+(which includes GET REST actions) is supported.
+
++----------------------------+----------+-----------------------------------------------+----------+
+| Attribute Name             | Type     | Description                                   | Default  |
++============================+==========+===============================================+==========+
+| read                       | parent   | ACL data for read operation.                  | None     |
+|                            | element  |                                               |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| users                      | [string] | (optional) List of user ids. This needs to be | []       |
+|                            |          | a user id as returned by Keystone.            |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| creator-only               | boolean  | (optional) Flag to mark a secret private so   | `false`  |
+|                            |          | that the user who created the secret and      |          |
+|                            |          | ``users`` specified in above list can only    |          |
+|                            |          | access the secret. Pass `true` to mark the    |          |
+|                            |          | secret private.                               |          |
++----------------------------+----------+-----------------------------------------------+----------+
+
+
+Request/Response (Set ACL):
+***************************
+
+.. code-block:: none
+
+    Request:
+
+    PUT /v1/secrets/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":{
+        "users":[
+          {user_id1},
+          {user_id2},
+          .....
+        ],
+        "creator-only":{creator-only-flag}
+      }
+    }
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
+
+Request/Response (Replace ACL):
+******************************
+
+.. code-block:: none
+
+    PUT /v1/secrets/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":{
+        "users":[
+          {user_id1},
+          {user_id2},
+          .....
+        ],
+        "creator-only":{creator-only-flag}
+      }
+    }
+
+    Response:
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
+
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successfully set/replaced secret ACL.                                       |
++------+-----------------------------------------------------------------------------+
+| 400  | Bad Request.                                                                |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Secret not found for the given UUID.                                        |
++------+-----------------------------------------------------------------------------+
+| 415  | Unsupported Media Type.                                                     |
++------+-----------------------------------------------------------------------------+
+
+
+.. _patch_secret_acl:
+
+PATCH /v1/secrets/{uuid}/acl
+############################
+
+Updates existing ACL for a given secret. This method can be used to apply partial changes on
+existing ACL settings. Client can update the `users` list and enable or disable `creator-only`
+flag for existing ACL. List of provided users replaces existing users if any. For an existing
+list of provided users from an ACL definition, pass empty list [] for `users`.
+
+Returns an ACL reference in success case.
+
+.. note::
+    
+    PATCH API support will be changing in near future.
+
+Attributes
+**********
+
++----------------------------+----------+-----------------------------------------------+----------+
+| Attribute Name             | Type     | Description                                   | Default  |
++============================+==========+===============================================+==========+
+| read                       | parent   | ACL data for read operation.                  | None     |
+|                            | element  |                                               |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| users                      | [string] | (optional) List of user ids. This needs to be | None     |
+|                            |          | a user id as returned by Keystone.            |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| creator-only               | boolean  | (optional) Flag to mark a secret private so   | None     |
+|                            |          | that the user who created the secret and      |          |
+|                            |          | ``users`` specified in above list can only    |          |
+|                            |          | access the secret. Pass `true` to mark the    |          |
+|                            |          | secret private.                               |          |
++----------------------------+----------+-----------------------------------------------+----------+
+
+Request/Response (Updating creator-only flag):
+**********************************************
+
+.. code-block:: none
+
+    PATCH /v1/secrets/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":
+        {
+          "creator-only":true
+        }
+    }
+
+    Response:
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
+
+
+Request/Response (Removing all users from ACL):
+***********************************************
+
+.. code-block:: none
+
+    PATCH /v1/secrets/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":
+        {
+          "users":[]
+        }
+    }
+
+    Response:
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/secrets/{uuid}/acl"}
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successfully updated secret ACL.                                            |
++------+-----------------------------------------------------------------------------+
+| 400  | Bad Request.                                                                |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Secret not found for the given UUID.                                        |
++------+-----------------------------------------------------------------------------+
+| 415  | Unsupported Media Type.                                                     |
++------+-----------------------------------------------------------------------------+
+
+.. _delete_secret_acl:
+
+DELETE /v1/secrets/{uuid}/acl
+##############################
+
+Delete ACL for a given secret. No content is returned in the case of successful
+deletion.
+
+Request/Response:
+*****************
+
+.. code-block:: none
+
+    DELETE /v1/secrets/{uuid}/acl
+    Headers:
+        X-Auth-Token: {token_id}
+
+    Response:
+    HTTP/1.1 200 OK
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successfully deleted secret ACL.                                            |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Secret not found for the given UUID.                                        |
++------+-----------------------------------------------------------------------------+
+
+Container ACL API
+==================
+
+.. _get_container_acl:
+
+GET /v1/containers/{uuid}/acl
+#############################
+Retrieve the ACL settings for a given container.
+
+If no ACL is defined for that container, then :ref:`Default ACL<default_implicit_acl>` is returned.
+
+Request/Response (With ACL defined):
+************************************
+
+.. code-block:: none
+
+    Request:
+
+    GET /v1/containers/{uuid}/acl
+    Headers:
+        X-Auth-Token: {token_id}
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {
+      "read":{
+        "updated":"2015-05-12T20:08:47.644264",
+        "created":"2015-05-12T19:23:44.019168",
+        "users":[
+          {user_id1},
+          {user_id2},
+          .....
+        ],
+        "creator-only":{creator-only-flag}
+      }
+    }
+
+
+Request/Response (With no ACL defined):
+***************************************
+
+.. code-block:: none
+
+    Request:
+
+    GET /v1/containers/{uuid}/acl
+    Headers:
+        X-Auth-Token: {token_id}
+
+    Response:
+
+    HTTP/1.1 200 OK
+    {
+      "read":{
+        "creator-only": false
+      }
+    }
+
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successful request.                                                         |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Container not found for the given UUID.                                     |
++------+-----------------------------------------------------------------------------+
+
+.. _put_container_acl:
+
+PUT /v1/containers/{uuid}/acl
+#############################
+Create new or replaces existing ACL for a given container.
+
+This call is used to add new ACL for an container. If the ACL is already set on a container,
+this method will replace it with the requested ACL settings. In case of create (first new explicit
+ACL) or replace existing ACL, 200 is returned in both cases. To delete existing users from
+an ACL definition, pass empty list [] for `users`.
+
+Returns an ACL reference in success case.
+
+Attributes
+**********
+
+The ACL resource detailed in this page allows access to individual containers to be controlled.
+This access is configured via operations on those containers. Currently only the 'read' operation
+(which includes GET REST actions) is supported.
+
++----------------------------+----------+-----------------------------------------------+----------+
+| Attribute Name             | Type     | Description                                   | Default  |
++============================+==========+===============================================+==========+
+| read                       | parent   | ACL data for read operation.                  | None     |
+|                            | element  |                                               |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| users                      | [string] | (optional) List of user ids. This needs to be | []       |
+|                            |          | a user id as returned by Keystone.            |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| creator-only               | boolean  | (optional) Flag to mark a container private   | `false`  |
+|                            |          | so that the user who created the container and|          |
+|                            |          | ``users`` specified in above list can only    |          |
+|                            |          | access the container. Pass `true` to mark the |          |
+|                            |          | container private.                            |          |
++----------------------------+----------+-----------------------------------------------+----------+
+
+
+Request/Response (Set ACL):
+***************************
+
+.. code-block:: none
+
+    Request:
+
+    PUT /v1/containers/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":{
+        "users":[
+          {user_id1},
+          {user_id2},
+          .....
+        ],
+        "creator-only":{creator-only-flag}
+      }
+    }
+
+    Response:
+
+    HTTP/1.1 201 Created
+    {"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
+
+Request/Response (Replace ACL):
+******************************
+
+.. code-block:: none
+
+    PUT /v1/containers/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":{
+        "users":[
+          {user_id1},
+          {user_id2},
+          .....
+        ],
+        "creator-only":{creator-only-flag}
+      }
+    }
+
+    Response:
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
+
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successfully set/replaced  container ACL.                                   |
++------+-----------------------------------------------------------------------------+
+| 400  | Bad Request.                                                                |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Container not found for the given UUID.                                     |
++------+-----------------------------------------------------------------------------+
+| 415  | Unsupported Media Type.                                                     |
++------+-----------------------------------------------------------------------------+
+
+
+.. _patch_container_acl:
+
+PATCH /v1/containers/{uuid}/acl
+###############################
+
+Update existing ACL for a given container. This method can be used to apply partial changes
+on existing ACL settings. Client can update `users` list and enable or disable `creator-only`
+flag for existing ACL. List of provided users replaces existing users if any. For an existing
+list of provided users from an ACL definition, pass empty list [] for `users`.
+
+Returns an ACL reference in success case.
+
+.. note::
+    
+    PATCH API support will be changing in near future.
+
+Attributes
+**********
+
++----------------------------+----------+-----------------------------------------------+----------+
+| Attribute Name             | Type     | Description                                   | Default  |
++============================+==========+===============================================+==========+
+| read                       | parent   | ACL data for read operation.                  | None     |
+|                            | element  |                                               |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| users                      | [string] | (optional) List of user ids. This needs to be | None     |
+|                            |          | a user id as returned by Keystone.            |          |
++----------------------------+----------+-----------------------------------------------+----------+
+| creator-only               | boolean  | (optional) Flag to mark a container private   | None     |
+|                            |          | so that the user who created the container and|          |
+|                            |          | ``users`` specified in above list can only    |          |
+|                            |          | access the container. Pass `true` to mark the |          |
+|                            |          | container private.                            |          |
++----------------------------+----------+-----------------------------------------------+----------+
+
+Request/Response (Updating creator-only flag):
+**********************************************
+
+.. code-block:: none
+
+    PATCH /v1/containers/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":
+        {
+          "creator-only":true
+        }
+    }
+
+    Response:
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
+
+
+Request/Response (Removing all users from ACL):
+***********************************************
+
+.. code-block:: none
+
+    PATCH /v1/containers/{uuid}/acl
+    Headers:
+        Content-Type: application/json
+        X-Auth-Token: {token_id}
+
+    Body:
+    {
+      "read":
+        {
+          "users":[]
+        }
+    }
+
+    Response:
+    HTTP/1.1 200 OK
+    {"acl_ref": "https://{barbican_host}/v1/containers/{uuid}/acl"}
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successfully updated container ACL.                                         |
++------+-----------------------------------------------------------------------------+
+| 400  | Bad Request.                                                                |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Container not found for the given UUID.                                     |
++------+-----------------------------------------------------------------------------+
+| 415  | Unsupported Media Type.                                                     |
++------+-----------------------------------------------------------------------------+
+
+.. _delete_container_acl:
+
+DELETE /v1/containers/{uuid}/acl
+################################
+
+Delete ACL for a given container. No content is returned in the case of successful
+deletion.
+
+Request/Response:
+*****************
+
+.. code-block:: none
+
+    DELETE /v1/containers/{uuid}/acl
+    Headers:
+        X-Auth-Token: {token_id}
+
+    Response:
+    HTTP/1.1 200 OK
+
+
+HTTP Status Codes
+*****************
+
++------+-----------------------------------------------------------------------------+
+| Code | Description                                                                 |
++======+=============================================================================+
+| 200  | Successfully deleted container ACL.                                         |
++------+-----------------------------------------------------------------------------+
+| 401  | Missing or Invalid X-Auth-Token. Authentication required.                   |
++------+-----------------------------------------------------------------------------+
+| 403  | User does not have have permission to access this resource.                 |
++------+-----------------------------------------------------------------------------+
+| 404  | Container not found for the given UUID.                                     |
++------+-----------------------------------------------------------------------------+
\ No newline at end of file