Customizing Annotation Permissions

PSPDFKit for Web allows you to control the actions that can be performed by users on a loaded document.

Launch Demo

There are different ways in which you can set the permissions depending on whether you’re using a Standalone or Server-Backed setup. They can be categorized as follows:

UI-Level Permissions

These permissions are enforced on the viewer and are applicable on all the documents loaded in the viewer. They can be specified on the client side or on server side (if you have a Server-Backed setup) using the JSON Web Token (JWT). These permissions aren’t included in the PDF once they’re exported.

Client-Side Permissions

These permissions work for both standalone and server setups.

Opening a Document in Read-Only Mode

You can set the viewer to read-only mode using PSPDFKit.ViewState#readOnly:

PSPDFKit.load({
  ...defaultConfiguration,
  initialViewState: new PSPDFKit.ViewState({ readOnly: true })
});

When read-only mode is activated, the UI for creating, updating, and deleting annotations will be completely hidden. In addition, the user will no longer be able to select annotations.

However, it’s still possible to add annotations programmatically.

Disabling Editing Specific Annotations

The read-only mode discussed in the last section makes all the annotations in a document non-editable. There might be situations in which you want to disable editing specific annotations. This can be achieved by using PSPDFKit.Configuration#isEditableAnnotation.

As an example, the following code makes all the ink annotations in a document non-editable:

PSPDFKit.load({
  ...defaultConfiguration,
  isEditableAnnotation: (annotation) =>
    !(annotation instanceof PSPDFKit.Annotations.InkAnnotation)
});

Disabling Editing Based on Custom Logic

There might be situations where you only want to enable editing of certain annotations for certain users. You can achieve this by specifying the user roles in the annotation’s custom data:

const annotationWithState = annotation.set("customData", {
  forUserRoles: ["manager", "editor"]
});

instance.update(delayedAnnotation);

You can make annotations editable based on their roles:

PSPDFKit.load({
  ...defaultConfiguration,
  isEditableAnnotation: (annotation) =>
    annotation.customData.forUserRules.includes(currentUser.role)
});

Now an annotation will only be editable when its forUserRoles array contains the role of the currentUser.

Server-Side Permissions

These permissions work for Server-Backed mode. All the methods explained in the client-side permissions section are also applicable here, but if you are using Server-Backed mode, you can set these permissions in the JWT, which is more secure and scalable. The permissions set via JWT can’t be overridden on the client side.

Opening a Document in Read-Only Mode

If you omit the write permission from the JWT, the document won’t be editable:

const jwtClaims = {
  document_id: "id",
  permissions: ["read-document"] // "write" is missing here
};

You can read about different kinds of document permissions that can be set in the JWT in our Client Authentication guide.

Collaboration Permissions

Collaboration Permissions is a feature that gives you a fine-grained permission system for defining actions allowed by individual users when multiple users are working on the same document. Please read our Collaboration Permissions guide to learn more about it.

Document-Level Permissions

The PDF specification defines a series of flags that can be set on a document to determine what a user can do with a document. These permissions are persisted even after you’ve exported a PDF.

PSPDFKit honors the permissions set on a document and enables or disables certain platform features based on the permission configuration. If you don’t want this behavior, you can disable it using IGNORE_DOCUMENT_PERMISSIONS:

PSPDFKit.Options.IGNORE_DOCUMENT_PERMISSIONS = true;

PSPDFKit.load(defaultConfiguration);

You can read more about these permissions in our Document Permissions guide.