---
title: "User permissions in instant sync: A guide"
canonical_url: "https://www.nutrient.io/guides/document-engine/instant-synchronization/permissions/edit-permissions/"
md_url: "https://www.nutrient.io/guides/document-engine/instant-synchronization/permissions/edit-permissions.md"
last_updated: "2026-05-22T14:49:21.615Z"
description: "Learn to manage user permissions for annotations and comments in your applications using JWT and Collaboration Permissions for instant synchronization."
---

# 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](https://www.nutrient.io/guides/document-engine/instant-synchronization/permissions/overview.md). 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 Nutrient 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](https://www.nutrient.io/guides/document-engine/instant-synchronization/get-started.md).

The permission attached to individual records is based on the [permission string](https://www.nutrient.io/guides/document-engine/instant-synchronization/permissions/set-permissions.md) 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](https://www.nutrient.io/guides/document-engine/instant-synchronization/permissions/set-permissions.md#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 [Nutrient Web SDK](https://www.nutrient.io/guides/web.md), you can create individual annotations, comments, or form fields using the [`instance.create`](https://www.nutrient.io/api/web/PSPDFKit.Instance.html#create) API:

```js

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](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#create) 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:

```sh

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](https://www.nutrient.io/guides/document-engine/instant-synchronization/permissions/overview.md), the authenticated client needs to have the permission to change groups. For example, with the [Web SDK](https://www.nutrient.io/guides/web/collaboration-permissions/introduction-to-collaboration-permissions.md) use the [`instance.update()`](https://www.nutrient.io/api/web/classes/NutrientViewer.Instance.html#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:

```js

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 Nutrient frontend SDKs:

- [Nutrient Web SDK](https://www.nutrient.io/guides/web/collaboration-permissions/introduction-to-collaboration-permissions.md)

- [Nutrient iOS SDK](https://www.nutrient.io/guides/ios/collaboration-permissions/introduction-to-collaboration-permissions.md)
---

## Related pages

- [Setting user collaboration permissions effectively](/guides/document-engine/instant-synchronization/permissions/set-permissions.md)
- [Master collaboration permissions in Document Engine](/guides/document-engine/instant-synchronization/permissions/content-ownership.md)
- [Understanding collaboration permissions for documents](/guides/document-engine/instant-synchronization/permissions/example.md)
- [Manage document collaboration permissions securely](/guides/document-engine/instant-synchronization/permissions/overview.md)