Sharing Content

Managing access

This section explains how to use the Connect Server APIs to manage user permissions to your deployed content items. See the Deploying Content section for help creating content and deploying your code.

These recipes use bash snippets and rely on curl to perform HTTP requests. We use the CONNECT_SERVER, CONNECT_API_KEY, and CONTENT_GUID environment variables introduced in the Getting Started and Deploying Content sections of this cookbook.

Sharing content with a collaborator

Workflow

  1. To share content with a user or group, you first need the user or group’s GUID. See the Users and Groups sections for information about how to query users and groups.

  2. Next, add the user to the content Access Control List (ACL) with the role you would like for them to have by making a call to POST /v1/content/{guid}/permissions endpoint.

    Valid roles are:

    • viewer for read-only access
    • owner for full collaborator access
Note

The /permissions API cannot be used to transfer content ownership between users. Content ownership transfers must be accomplished using the usermanager CLI tool.

Here is an example of using the POST /v1/content/{guid}/permissions endpoint to add the user to the ACL:

USER_GUID="93f250d0-8f16-4095-befb-9d902b16918c"
DATA='{"principal_guid": "'${USER_GUID}'",
       "principal_type": "user",
       "role": "owner"}'

curl --silent --show-error -L --max-redirs 0 --fail \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    -X POST --data-raw "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/content/${CONTENT_GUID}/permissions"

Removing a collaborator

You can remove or change a collaborator’s permissions by updating or deleting the permission entry created for that user with the DELETE /v1/content/{guid}/permissions/{id} endpoint.

Workflow

  1. First, use the GET /v1/content/{guid}/permissions request endpoint to list the permissions associated with the content and get the ID of the permission entry to delete.

  2. Next, send a DELETE /v1/content/{guid}/permissions/{id} request to delete the permission entry for the user.

Here is an example of how to use a GET request to list the permissions associated with the content:

curl --silent --show-error -L --max-redirs 0 --fail \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    "${CONNECT_SERVER}__api__/v1/content/${CONTENT_GUID}/permissions"
# => [
# =>   {
# =>     "id": "412",
# =>     "content_guid": "19aae5d7-7127-445d-af54-bddb1ab4c9d6",
# =>     "principal_guid": "af033b9a-38f0-4b02-ad78-352070f371e3",
# =>     "principal_type": "user",
# =>     "role": "owner"
# =>   },
# =>   {
# =>   "id": "414",
# =>   "content_guid": "19aae5d7-7127-445d-af54-bddb1ab4c9d6",
# =>   "principal_guid": "4ba1bb81-e0b8-4d41-a0e8-2d125d7004d9",
# =>   "principal_type": "user",
# =>   "role": "viewer"
# =>   },
# => ]

Then, delete the permission entry for the user you want to remove by using a DELETE request and specifying its ID in the URL. For example:

curl --silent --show-error -L --max-redirs 0 --fail \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    -X DELETE \
    "${CONNECT_SERVER}__api__/v1/content/${CONTENT_GUID}/permissions/412"

Updating access

Workflow

  1. If you haven’t already retrieved the permission ID, use the GET /v1/content/{guid}/permissions endpoint to list permissions for the content item.

  2. To update the user’s permission entry with a new role, use a PUT request with the permission ID in the URL and specify the new permission settings.

Here is an example of the PUT /v1/content/{guid}/permissions/{id} endpoint updating a user’s permissions:

DATA='{"principal_guid": "'${USER_GUID}'",
       "principal_type": "user",
       "role": "viewer"}'

curl --silent --show-error -L --max-redirs 0 --fail \
    -H "Authorization: Key ${CONNECT_API_KEY}" \
    -X PUT --data-raw "${DATA}" \
    "${CONNECT_SERVER}__api__/v1/content/${CONTENT_GUID}/permissions/412"