Setting User Collaboration Permissions

The permission to perform different actions on a document is defined in the JSON Web Token (JWT) using the collaboration_permissions property:

{
	...otherProperties,
	"collaboration_permissions": ['annotations:view:all', 'annotations:edit:all'],
	"user_id": 'John',
};

The value of the collaboration_permissions property is an array of permission strings. A permission string consists of three parts written in the <content-type>:<action>:<scope> format. This guide covers all the possible values of content-type, action, and scope, one by one.

content-type

This refers to the type of record you want to apply a particular permission to. Currently, we support annotations and comments, so content-type has the following possible values:

  • annotations — This applies to all the annotations in the document.

  • comments — This applies to all the comments in the document. To use comments in the document, you’ll need a separate license for Instant Comments.

action

This defines the action for which you want to define the permission. The following actions are supported:

  • view — This defines whether or not a content type is visible to a user.

  • edit — This defines whether or not a user is allowed to edit a content type.

  • delete — This defines whether or not a user is allowed to delete a content type.

  • reply — This defines whether or not a user is allowed to reply to a comment thread. This action is only applicable to the comments content type.

  • set-group — This is a special permission that allows a user to create a content type with a group that’s different from the default group defined in the JWT. It’s also needed if you want to allow a user to change the group of existing annotations or comments. You can read more about this below in the group section.

scope

This is used to scope the annotations and comments the permissions should be applied to. You can define this in the following ways:

  • all — This means the action is allowed for all the content types. For example, annotations:edit:all means a user is allowed to edit all the annotations.

  • self — This means the action is allowed for all the content types that were created by the current user. For example, annotations:delete:self means a user is allowed to delete the annotations they created.

  • createdBy= — This means the action is allowed for the content types created by a particular user ID. If you don’t pass the value of the user ID, the action is applicable to all the content types with the user ID null. For example, annotations:view:createdBy= means that all annotations with the user ID null are visible.

  • group= — This means that the action is allowed for all the content types with a particular group. If you don’t pass the group value, the permission is applicable to all the records with the group set to null. For example, annotations:view:group= means that all annotations with the group set to null are visible.

The user_id defined in the JWT parameters helps us define creator-based permissions like self and createdBy=<user-id>.

We combine all three properties described above to form the collaboration permissions configuration.

group

The group property is used to allow greater flexibility when declaring permissions and managing access to content.

Changing the group of an annotation or a comment after its creation isn’t supported by the Instant iOS SDK at the moment. However, you can still mutate the group of a record if you’re using the Web SDK. This change will still apply to the user using the Instant iOS SDK.

You can view the group of a particular annotation by accessing the instantRecordGroup property:

let annotation: Annotation = ...
let annotationGroup = annotation.instantRecordGroup

Default Group

If you want to set one group for all the annotations and comments created by a user, you have to set a default_group property in the JWT. If set, whenever you create a new annotation or comment, it’ll automatically assign that group to them.

If you want to change the defaultGroup so that a new group applies to all the newly created annotations and comments automatically, you can use InstantDocumentDescriptor.overrideDefaultGroup(with:). Please keep in mind that this only stores the new group locally to add it to the newly created annotations and comments. This won’t change the original default_group stored on the server.

You can also undo this change and go back to the original default_group set in the JWT by using InstantDocumentDescriptor.resetDefaultGroup().

You can read more about the different ways in which you can change the permission of a record in our changing permissions guide.

Accessing Permissions

In addition to the group on Annotation instances, you can use the instantRecordOperations property to check for the available permissions attached to an individual annotation:

let annotation: Annotation = ...
let permissions = annotation.instantRecordOperation
let canDelete = recordOperations.contains(.delete)