Client Authentication in PSPDFKit Instant

Instant uses JSON Web Tokens (JWTs) for authentication at a very granular level: the layer.

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, please 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 claim — in the simplest case, you can use the catchall value all

  • An expiration date in the standard exp 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 and iat 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, PSPDFKit 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, please refer to the Collaboration Permissions Overview 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.