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. PSPDFKit Server 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 Server APIs and how it changes during document lifecycle.
Creator is an immutable property of every piece of content created with PSPDFKit Server. 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
You can also pass the
user_id parameter when creating annotations and comments through Server API. As with the JWT, if you don’t provide
user_id in either of these APIs, the default of
null will be used.
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.
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 Server APIs or PSPDFKit for Web. You can read more in the group section of the Introduction to Collaboration Permissions guide to find out more about the use of group 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 Server API.
Comments, on the other hand, can have a completely different group than their root annotation.
With Server 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.
Apart from APIs that directly create or modify content — like the annotation creation API — other functionality provided by Server 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:
When you upload a document, the creator and group of every piece of content is
Copying a document copies the creator and group information from the original document.
Creating a layer with a
source_layer_nameparameter copies the creator and group information from the source layer.
Duplicating a page copies the creator and group information of content on that page.
Importing a document by ID (and optionally layer name) copies the creator and group information from that document.