Manage user permissions for instant synchronization

This guide covers different ways to change permissions of both newly created annotations, form fields, and comments (referred to as records in the rest of the guide) and already existing ones while using Collaboration Permissions. Changing the permission of newly created records means creating records with permissions different from the default permission based on the existing JSON Web Token (JWT).

Note that some of the examples in this guide make use of JavaScript along with PSPDFKit’s Web SDK. For guidance on using Instant sync with specific mobile platforms — iOS, Android, Flutter, and React Native — refer to the guides for those platforms here.

The permission attached to individual records is based on the permission string of the <content-type>:<action>:<scope> format present in the JWT. For example, the annotations:edit:self permission string means that the user has the permission to edit all the annotations that were created by the user (“self” scope). In this example, “self” is a scope that’s used to identify all the annotations for which the edit action should be allowed. The different possible values of scopes can be categorized as follows:

creator based — Scopes like self and createdBy=<creator-name> fall under this category. This scoping depends on the user_id claim defined in the JWT. The claim cannot be changed once a record has been created, so this scope is immutable.
group based — Scopes of the form group=<group-name> fall under this category. This scope is mutable, which means you can change the group of a record, provided you have the appropriate permission to do so.

This means that the permission attached to a record is either based on who created the record or the group of that record. Since the creator of the record is immutable, if you want to change the permissions of existing or newly created records, you’ll have to change the group.

In all the scenarios mentioned below, assume that the default_group claim set in the JWT is group1.

Creating Records with Different Groups

There are multiple ways you can override the default group of newly created annotations, form fields, or comments provided in the JWT. Regardless of how you create them, if you’re assigning a different group to them, you should have the necessary permission.

For example, if you want to create an annotation with the group set to group2 instead of group1 (which is the default group), you should have the permission string annotations:set-group:group=group2 in the collaboration_permissions claim of your JWT. If you don’t have this permission, all the methods described below will throw an error.

Once you create an annotation with a different group, the permissions applicable to that group will be applicable on it instead of the permissions that were applicable to the ones with the default group defined in the JWT.

For Individual Records

With the PSPDFKit for Web SDK, you can create individual annotations, comments, or form fields using the instance.create API:

const inkAnnotation = new PSPDFKit.Annotations.InkAnnotation({
  ...otherOptions,
  group: "group2"
});

const [createdAnnotationID] = await instance.create(inkAnnotation);

Changing the Group of an Existing Record

You can change the group of an existing record using either Document Engine’s Upstream API or one of the client SDKs.

To change the group of an existing annotation record using the Upstream API, you can make the following request:

curl -X PUT http://localhost:5000/api/documents/{documentID}/annotations \
  --header 'Authorization: Token token=secret' \
  --header 'content-type: application/json' \
  --data '{
            "annotations":
              [
                {
                  "content":{
                   ...
                  },
                  "user_id":"string",
                  "id":"annotation-id-01",
                  "group": "annotation-group"   // SPECIFY THE NEW GROUP NAME HERE
                }
              ]
          }'

Note that when changing groups with the /api/documents/{documentID}/annotations endpoint, permissions do not apply.

However, when changing the group in any of our client SDKs, the authenticated client needs to have the permission to change groups. For example, with the Web SDK use the instance.update() API to change the group of a given record. As mentioned earlier, you’ll need the appropriate permission to do this.

Specifically, as shown in the following code, if you want to change the annotation group from group1 to group2, make sure that the annotations:set-group:group=group1 permission string is present in the collaboration_permissions property of your JWT:

const inkAnnotation = (await instance.getAnnotations(0)).get(0);
const _inkAnnotation = inkAnnotation.set("group", "group2");

const [updateAnnotationID] = await instance.update(_inkAnnotation);

The code above will change the group of the ink annotation from "group1" to "group2".

Supported Client Platforms

Collaboration Permissions is available in the following PSPDFKit frontend SDKs: