Storing an ACL

Content Platform Tenant Management Help

Version
9.7.x
File Size
4269 KB
Audience
anonymous
Part Number
MK-95HCPH002-19

You use the HTTP PUT method to store or replace an ACL for an existing object. ACLs can be specified in XML or JSON format. Unlike storing annotations, you can store an ACL for an object under retention.

An ACL is stored as a single unit. You can add it or replace it in its entirely, but you cannot add to or change an existing ACL. If you store an ACL for an object that already has an ACL, the new ACL replaces the existing ACL.

When you store an ACL for an object, the ACL is also stored for all old versions of that object.

You can use the HCP Search Console to modify ACLs on multiple objects with a single operation.

Access permission

To store or replace an ACL for an object, you need write ACL permission.

Usage consideration

The PUT of an ACL may fail with an HTTP 409 (Conflict) error code if a large number of clients try to store ACLs for multiple objects at the same time. In this case, limit the number of concurrent requests from clients to the namespace.

Request header

PUT /rest/directory/file?type=acl HTTP/1.1
Parameter Required Description
directory Yes Folder name.
file Yes Name of the file, including file extension.
type Yes Use the value acl.

Response headers

This operation does not return any request-specific headers.

Status codes

The table below describes the HTTP status codes that have specific meaning for this request.

Code Meaning Description
201 Created HCP successfully stored the ACL.
400 Bad Request

One of:

  • The request is trying to store an ACL in a namespace for which ACLs are not enabled.
  • The ACL is not well-formed XML or JSON.
  • The ACL includes an invalid entry or an invalid value for an entry.
  • The ACL does not include a required entry.
  • The ACL specifies a user, group, or domain that doesn’t exist.
  • The ACL specifies an AD user or group but doesn’t include the domain entry.
  • The ACL specifies an AD user or group, but the namespace does not support Active Directory authentication.
  • Multiple name entries include the same user or group. A user or group can be specified in only one name entry in an ACL.
  • The permissions you have specified in the ACL exceed your user permissions.
  • The request is trying to store an ACL that contains more than one thousand access control entries. HCP cannot store ACLs that contain more than one thousand access control entries.
  • The request has a Content-Encoding header that specifies gzip, but the ACL is not in gzip-compressed format.
  • The URL in the request is not well-formed.
  • The request contains an unsupported query parameter or an invalid value for a query parameter.
  • The request contains an If-Match, If-None-Match, If-Modified-Since, or If-Unmodified-since header.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

403 Forbidden

One of:

  • The Authorization header or hcp-ns-auth cookie specifies invalid credentials.
  • The namespace requires client authentication, and the request does not have an Authorization header or hcp-ns-auth cookie.
  • You don’t have write or write ACL permission.
  • The namespace does not exist.
  • The access method (HTTP or HTTPS) is disabled.

If more information about the error is available, the HTTP response headers include the HCP-specific X‑HCP-ErrorMessage header.

404 Not Found

One of:

  • HCP could not find the object for which you’re trying to store an ACL.
  • The URL contains a symbolic link to a directory anywhere other than in the last component.
415 Unsupported Media Type

One of:

  • The request has a Content-Encoding header with a value other than gzip.
  • The request has a Content-Type header with a value other than application/xml or application/json.
  • The request has a Content-Type header with a value that doesn’t correspond to the content type of the ACL body.

Example: Storing an ACL for an object

Here’s a sample HTTP PUT request that stores the ACL defined in the

Q1_2012.acl.xml file for an existing object named Q1_2012.ppt.

Request with curl command line

curl -k -H "Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d"
    -iT Q1_2012.acl.xml -H "Content-Type: application/xml"
    "https://finance.europe.hcp.example.com/rest/quarterly_rpts/
    Q1_2012.ppt?type=acl"

Request in Python using PycURL

import pycurl
import os
filehandle = open("Q1_2012.acl.xml", 'rb')
curl = pycurl.Curl()
curl.setopt(pycurl.HTTPHEADER, ["Authorization: HCP
  bXl1c2Vy:3f3c6784e97531774380db177774ac8d"])
curl.setopt(pycurl.URL, "https://finance.europe.hcp.example.com \
  /rest/quarterly_rpts/Q1_2012.ppt?type=acl")
curl.setopt(pycurl.SSL_VERIFYPEER, 0)
curl.setopt(pycurl.SSL_VERIFYHOST, 0)
curl.setopt(pycurl.UPLOAD, 1)
curl.setopt(pycurl.INFILESIZE, os.path.getsize("Q1_2012.acl.xml"))
curl.setopt(pycurl.READFUNCTION, filehandle.read)
curl.perform()
print curl.getinfo(pycurl.RESPONSE_CODE)
curl.close()
filehandle.close()

Request headers

PUT /rest/quarterly_rpts/Q1_2012.ppt?type=acl HTTP/1.1
Host: finance.europe.hcp.example.com
Authorization: HCP bXl1c2Vy:3f3c6784e97531774380db177774ac8d
Content-Length: 246

Response headers

HTTP/1.1 201 Created
X-HCP-ServicedBySystem: hcp.example.com
Location: /rest/quarterly_rpts/Q1_2012.ppt
X-HCP-Time: 1334772280
Content-Length: 0