Master collaboration permissions in Document Engine

Collaboration permissions allow you to define what actions are allowed on a piece of content in a document (annotations, Instant Comments, or form fields) based on who created it and what its group is. Document Engine tracks this information for all annotations, comments, and form fields in every document.

This guide aims to describe both how you can manage this information via Document Engine APIs and how it changes during the document lifecycle.

Creator

Creator is an immutable property of every piece of content created with Document Engine. When you specify a user_id in the JSON Web Token (JWT) used to authenticate PSPDFKit for Web, each annotation, comment, and form field created is attributed to that user. If the JWT claims don’t include user_id, the creator of all content is set to null.

You can also pass the user_id parameter when creating annotations and comments through Document Engine’s API. As with the JWT, if you don’t provide user_id in either of these APIs, the default of null will be used.

To inspect which creator is assigned to each piece of content, see the createdBy property when fetching annotations and comments.

Note that even though it’s possible to assign and fetch the creator of form field values, this information isn’t useful, because you can’t specify form field permissions based on their creator.

Group

The group property was introduced to allow greater flexibility when declaring permissions and managing access to content. Unlike the creator, the group of each annotation, comment, and form field is mutable, which means it can be changed either with Document Engine’s APIs or PSPDFKit for Web. You can read more in the group section of the guide on setting user collaboration permissions to find out more about the use of the group property with PSPDFKit for Web.

Form field values and widget annotations always inherit the group of the associated form field, and thus it’s not possible to set or update it directly via the Document Engine API.

Comments, on the other hand, can have a completely different group than their root annotation.

With Document Engine’s APIs, similar to the user_id, you can specify the group when creating annotations and comments. If you don’t provide the group, the default of null is used. You can also use the annotation update API to change the group of the annotation.

You can see what group is assigned to content by looking at the group property when fetching annotations, comments, and form field values.

Creator and Group in a Document Lifecycle

Apart from APIs that directly create or modify content — like the annotation creation API — other functionality provided by Document Engine may also add and update content in the document. This is a reference for how these operations affect the ownership information of annotations, comments, and form fields:

  1. When you upload a document, the creator and group of every piece of content is null.

  2. Copying a document copies the creator and group information from the original document.

  3. Creating a layer with a source_layer_name parameter copies the creator and group information from the source layer.

  4. Duplicating a page copies the creator and group information of content on that page.

  5. Importing a document by ID (and optionally layer name) copies the creator and group information from that document.

Supported Client Platforms

Collaboration Permissions is available in the following PSPDFKit frontend SDKs: