--- title: "Client authentication in Nutrient Instant" canonical_url: "https://www.nutrient.io/guides/ios/instant-synchronization/authentication/" md_url: "https://www.nutrient.io/guides/ios/instant-synchronization/authentication.md" last_updated: "2026-05-30T02:20:01.313Z" description: "Instant uses JSON Web Tokens (JWTs) for authentication at a very granular level: the layer. for Nutrient iOS SDK." --- # Client authentication in Nutrient Instant Instant uses [JSON Web Tokens](https://jwt.io/introduction) (JWTs) for authentication at a very granular level: [the layer](https://www.nutrient.io/guides/ios/pspdfkit-instant/instant-layers.md). You can think of an Instant layer as a scratchpad for annotations on top of a specific PDF file in Document Engine. There can be any number of these layers for a PDF file. However, every JWT you issue for use with Instant will reference exactly one layer. So each client will always be operating on a single layer at a time. ## Security considerations All JWTs are cryptographically signed. While it is _possible_ to generate valid JWTs on your users’ devices, **refrain from doing so**: Generating a JWT on a device requires the presence of a trusted private key. This opens up additional attack vectors for little-to-no tangible benefit. Instead, we urge you to generate JWTs exclusively on your backend server. ## Basic information Any client that’s supposed to have access to a layer needs a JWT signed by your backend. At the very least, the JWT needs to specify the following information: - The unique identifier for the PDF file in the user-defined `document_id` claim — you obtain this value when you import a PDF in Document Engine - The general permissions granted to the bearer of this JWT in the user-defined [`permissions`](#customizing-general-permissions) claim — in the simplest case, you can use the catchall value `all` - An expiration date in the standard [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) claim — a UNIX timestamp in seconds defining the latest date at which the client will have to request a new JWT from your backend to continue syncing Since access can always be revoked before the `exp` date is reached, consider picking expiration dates well into the future. This will help avoid unnecessary network roundtrips to obtain a new JWT and then reauthenticate the layer. ## Extended information In addition to the claims discussed in the previous section and the standard [`nbf`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5) and [`iat`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6) claims, Instant also supports the following user-defined claims in the JWT: - A unique identifier for the user authenticated by the JWT in the `user_id` claim — when omitted, an anonymous user is assumed and some functionality may be unavailable - The name of the layer on the PDF identified by the `document_id` in the `layer` claim — when omitted, the default layer for that PDF is implied - The human-readable name to use as the creator/author for all created annotations and comments in the `creator_name` claim — when omitted and not customized through [`Document.defaultAnnotationUsername`](https://www.nutrient.io/api/ios/documentation/pspdfkit/document/defaultannotationusername), Nutrient will prompt the user for a creator name exactly once - The unique identifier of the default group new annotations and comments are supposed to be associated with in the `group` claim — when omitted, the `null` group is implied (this only applies when your license includes the Collaboration Permissions component) To use the Collaboration Permissions component, the `user_id` claim mentioned above and the `collaboration_permissions` claim are both mandatory. For details on the latter, refer to the [collaboration permissions overview](https://www.nutrient.io/guides/web/collaboration-permissions/introduction-to-collaboration-permissions.md) guide. ## Customizing general permissions If you want to limit what a client can do on a layer, you need to replace the catchall string `all` with an array of strings for each permission you want to grant. While there are additional permissions available for use in web clients, iOS clients are only interested in the following ones: - `download` (mandatory) This permission is required for the initial download of the underlying PDF file without annotations. Although Instant stores the file locally for later use and shares the downloaded file across all of its layers, you should always include this permission when issuing a JWT for use with Instant on iOS. - `read-document` (mandatory) This permission is required to access the annotations on a layer. - `write` (optional) This permission is required if you want to let the bearer of the JWT create, update, or delete annotations or add comments on the layer. Omitting this permission will result in the client treating the layer as read-only. Changes made on other clients will still be synced to a client without the `write` permission, but that client will be prevented from making any changes of their own. JWTs without the write permission can be used for implementing things like the spectator side of a presenter mode, finalizing an agreement or contract as the last step before digitally signing it by multiple parties, or letting your users share their notes with others in real time, without the risk of the others accidentally changing something. --- ## Related pages - [Adding comments to PDFs on iOS](/guides/ios/comments/introduction-to-instant-comments.md) - [Streamline PDF annotation syncing on iOS](/guides/ios/pspdfkit-instant/syncing.md) - [Nutrient Instant and iOS data protection](/guides/ios/pspdfkit-instant/data-protection.md) - [Nutrient Instant and the document state](/guides/ios/pspdfkit-instant/instant-document-state.md) - [Frequently asked questions](/guides/ios/instant-synchronization/faq.md) - [PDF collaboration library for iOS](/guides/ios/instant-synchronization.md) - [Integrating real-time collaboration into your iOS application](/guides/ios/pspdfkit-instant/getting-started.md) - [Seamless offline PDF annotation and synchronization](/guides/ios/pspdfkit-instant/offline-support.md) - [Create PDF annotation layers on iOS](/guides/ios/pspdfkit-instant/instant-layers.md) - [Nutrient Instant usage](/guides/ios/pspdfkit-instant/usage.md)