Shared Folder Access REST API

This API exposes operations to allow the access to Folders that are shared with other users in their system to be managed. The users must have been invited to share access to the same area of the application as the user modifying shared folders.

This API can be accessed by users with the appropriate permissions and supports the following combination of operations:

Object	Supported operations
Folder Access	GET
Restrict Folder Access	PUT
Restrict Folder Hierarchy Access	PUT
Grant Folder Access	PUT
Grant Folder Hierarchy Access	PUT

Process

You want to restrict access for an individual user that currently has access to all of your folders.

Retrieve the userId of the user you wish to change access levels for. This is done by making a call to the User REST API to retrieve the list of existing users. For our examples below determine that user "John Smith" with id:00000000000292bf is the user we wish to change access for.
Retrieve the set of folderIds for your inventory through calls to the Folder REST API. This gives us the main advertising container: 00000000000063a4 and the child that we want to restrict "Blues Advertising Folder" with id: 00000000000063d3
Restrict hierarchy access for the user. This restricts the user's access to all folders under their Advertising and Publishing document hierarchies. It also ensures that any new folders created will also be restricted for that user. Don't worry any folders they create (provided their role allows it) will be available to them.
```
curl -s -H "Content-type: text/xml" -u yourUsername:yourPassword -X PUT https://localhost:10000/api/secure/restrictFolderHierarchyAccess/00000000000292bf
```
Grant folder access to the user for any folders you wish them to have access to. This means they will be able to perform the operations permitted for them by their role membership, from this point in the document hierarchy.
```
curl -s -H "Content-type: text/xml" -u yourUsername:yourPassword -X PUT https://localhost:10000/api/secure/grantFolderAccess/00000000000063d3/00000000000292bf
```
Continue to grant access to any other folders you want to expose to the user by repeating the command in the step above updating the folderId each time.

Retrieve Folder Access for a User

Only the GET method is supported to retrieve the folder access for a particular user. This API states, for the given user, whether they have been granted access to, or restricted access from each child folder of the given folder. This resource does not take into account any hierarchy access that may be in place for the user.

GET

Retrieve the list of available and restricted folders from a particular point in the tree for a given user.

https://{cxadbaseurl}/api/secure/folderAccess/{folderId}/{userId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
folderId - the folderId of an existing Folder
userId - the userId of the user you wish to retrieve container settings for

This XML example shows the contents returned from a typical GET call:

<?xml version="1.0" ?>
<cx:folderAccess xmlns:cx="http://cxense.com/cxad/api/cxad"
                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                 xsi:schemaLocation="http://cxense.com/cxad/api/cxad http://cxense.com/cxad/api/cxad/cxad.xsd">
    <cx:restrictedFolders>
        <cx:folder>
            <cx:folderId>000000000000584e</cx:folderId>
            <cx:name>A restricted folder</cx:name>
        </cx:folder>
        <cx:folder>
            <cx:folderId>000000000000584f</cx:folderId>
            <cx:name>Another restricted folder</cx:name>
        </cx:folder>
    </cx:restrictedFolders>
    <cx:accessibleFolders>
        <cx:folder>
            <cx:folderId>000000000000584d</cx:folderId>
            <cx:name>An accessible folder</cx:name>
        </cx:folder>
    </cx:accessibleFolders>
</cx:folderAccess>

Restrict Folder Access

Call this if you want to restrict a user's access to a particular folder and all documents beneath it. All operations at that point in the tree will be restricted from then on.

PUT

https://{cxadbaseurl}/api/secure/restrictFolderAccess/{folderId}/{userId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
folderId - the folderId of an existing Folder
userId - the userId of the user you are wanting to change access for

No XML data needs to accompany the request.

Restrict Folder Hierarchy Access

Call this if you want to restrict the user's access to all child documents under their Advertising and Publishing document hierarchies.

PUT

https://{cxadbaseurl}/api/secure/restrictFolderHierarchyAccess/{userId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
userId - the userId of the user you are wanting to change access for

No XML data needs to accompany the request.

NOTE: Access to this API has been refined as part of delivery and deployment of the following JIRA issue.

Error rendering macro 'jira' : com.atlassian.confluence.macro.MacroExecutionException: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Restricting hierarchy access is considered a general setting for a user, regardless of position in the document tree. Therefore, the folderId argument that was previously defined in the URL for this resource is no longer required. The URL above has been updated to reflect this change, however we will continue to support access using URLs in the earlier form.

https://{cxadbaseurl}/api/secure/restrictFolderHierarchyAccess/{folderId}/{userId}

Please note, any folderId argument supplied in the URL for this resource will be ignored and the result of the call will simply be to flag the given user as having restricted hierarchy access.

Grant Folder Access

Call this if you want to allow access for a user to a particular folder and all documents beneath it. All operations at that point in the tree will be available from then on. It is only necessary to call this if a restriction has been placed on a parent folder. The default behaviour of the system is to allow access to all folders under the area the user has been invited to.

PUT

https://{cxadbaseurl}/api/secure/grantFolderAccess/{folderId}/{userId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
folderId - the folderId of an existing Folder
userId - the userId of the user you are wanting to change access for

No XML data needs to accompany the request.

Grant Folder Hierarchy Access

Call this if you want to allow the user to access all child documents under their Advertising and Publishing document hierarchies. This removes any existing restrictions on child folders in the document hierarchy effectively returning the user back to their role permissions.

PUT

https://{cxadbaseurl}/api/secure/grantFolderHierarchyAccess/{userId}

Parameters:

cxadbaseurl the base URL of the Cxense Advertising system
userId - the userId of the user you are wanting to change access for

No XML data needs to accompany the request.

NOTE: Access to this API has been refined as part of delivery and deployment of the following JIRA issue.

Granting hierarchy access is considered a general setting for a user, regardless of position in the document tree. Therefore, the folderId argument that was previously defined in the URL for this resource is no longer required. The URL above has been updated to reflect this change, however we will continue to support access using URLs in the earlier form.

https://{cxadbaseurl}/api/secure/grantFolderHierarchyAccess/{folderId}/{userId}

Please note, any folderId argument supplied in the URL for this resource will be ignored and the result of the call will simply be to flag the given user as having full hierarchy access.

Last updated: January 19, 2022