Understanding collaboration permissions for documents

To understand Collaboration Permissions in detail, this guide provides an example of a PDF with multiple form fields that have to be filled out by a tenant and a landlord.

In this example, there are three parties:

  • Estate agent

  • Landlord

  • Tenant

The estate agent adds the form fields to the document and assigns them to the landlord and the tenant. The landlord can only fill out the fields assigned to them, and the tenant can only fill out the fields assigned to them.

Estate Agent

The estate agent will take a PDF form and add form fields to it. They’ll need the following permissions in the JSON Web Token (JWT):

// JWT claims:

{
  ...otherProperties,
  "collaboration_permissions": [
    "annotations:view:all",
    "annotations:edit:self",
    "annotations:delete:self",
    "form-fields:view:all",
    "form-fields:edit:all",
    "form-fields:delete:all",
    "form-fields:set-group:group=estateAgent",
    "form-fields:set-group:group=assignedToLandlord",
    "form-fields:set-group:group=assignedToTenant"
  ],
  "user_id": "id-1",
  "default_group": "estateAgent"
};

The following permission strings are required by the tenant:

  • annotations:view:all — This will allow the estate agent to view all the annotations in the document.

  • annotations:edit:self — This will allow the estate agent to edit annotations they created.

  • annotations:delete:self — This will allow the estate agent to delete annotations they created.

  • form-fields:view:all — This will allow the estate agent to view all the form fields and the associated widget annotations.

  • form-fields:edit:all — This will allow the estate agent to edit all the widget annotations.

  • form-fields:delete:all — This will allow the estate agent to delete all the form fields and related widget annotations.

  • form-fields:set-group:group=estateAgent — This will allow the estate agent to change the group of all the form fields and widget annotations with the group estateAgent. Keep in mind that all the newly created form fields and widget annotations will have the group set to estateAgent, since the estate agent’s default_group set in the JWT is estateAgent.

  • form-fields:set-group:group=assignedToLandlord — This will allow the estate agent to create widget annotations and form fields with the assignedToLandlord group directly. Also, they’ll be able to change the value of the group if they made a mistake.

  • form-fields:set-group:group=assignedToTenant — This will allow the estate agent to create widget annotations and form fields with the assignedToTenant group directly. They’ll also be able to change the group if they made a mistake.

These groups will be used to grant permission to the landlord and the tenant.

Landlord

The landlord should be able see all the annotations and form fields but shouldn’t be able to edit them. The landlord will be able to fill out the form fields that have the group set to assignedToLandlord.

To achieve this, the landlord will require the following parameters in the JWT:

// JWT claims:

{
  ...otherProperties,
  "collaboration_permissions": [
    "annotations:view:all",
    "form-fields:view:all",
    "form-fields:fill:group=assignedToLandlord"
  ],
  "user_id": "id-2",
  "default_group": "landlord"
};

The following permission strings are required by the landlord:

  • annotations:view:all — This will allow the landlord to view all the annotations.

  • form-fields:view:all — This will allow the landlord to view all the form fields and associated widget annotations.

  • form-fields:fill:group=assignedToLandlord — This will allow the landlord to fill out all the form fields in the document with the group set to assignedToLandlord. All other form fields will be read-only.

Tenant

The tenant should be able to view all the annotations and form fields but shouldn’t be able to edit them. The tenant will be able to fill out the form fields that have the group value set to assignedToTenant.

To achieve this, the landlord will require the following JWT parameters:

{
  ...otherProperties,
  "collaboration_permissions": [
    "annotations:view:all",
    "form-fields:view:all",
    "form-fields:fill:group=assignedToTenant"
  ],
  "user_id": "id-3",
  "default_group": "tenant"
};

The following permission strings are required by the tenant:

  • annotations:view:all — This will allow the tenant to view all the annotations.

  • form-fields:view:all — This will allow the tenant to view all the form fields and associated widget annotations.

  • form-fields:fill:group=assignedToTenant — This will allow the tenant to fill out all the form fields in the document with the group set to assignedToTenant. All other form fields will be read-only.

In this way, you can define different permissions for different users based on the parameters you include in the JWT.

Supported Client Platforms

Collaboration Permissions is available in the following PSPDFKit frontend SDKs: