CloudPDF
DocsPricing
Start building

Tokens for your users

When your users are signed in to your app, your server gives each of them a token for the document they open. The token says who they are, what they can do, and for how long. The browser holds only that token: never your API key, and never access to any other document.

import { permissions } from '@/lib/permissions';
 
const { token, expiresAt } = await cloudpdf.tokens.issue({
  tenantId,
  body: {
    kind: 'doc',
    docId: contract.documentId,
    sub: user.id,
    identity: { userId: user.id, displayName: user.name },
    scope: permissions.comment,
    expiresInSeconds: 3600,
  },
});

Your server makes tokens with an API key that has Viewer tokens on. A token gives only what the key itself may do inside documents, so a key that makes Comment tokens needs Inside documents on Write. permissions is a short file with the dashboard’s levels. Add PDFs to your app puts all of this in a route your pages call.

What a token says#

The fields go in body, with kind: 'doc':

FieldWhat it says
docIdWhich documentRequired
subWho the user is in your app: their idRequired
scopeWhat they can do: a level, plus Download, Print or Copy textRequired
expiresInSecondsHow long the token works: a minute to 90 daysRequired
identityTheir name and details, below
originsThe websites the token works on, such as ['https://app.fernquill.example']
layerNameWhich copy of the document their changes go into, below

Who they are#

identity puts a name on what they do:

FieldWhat it’s for
displayNameTheir name, shown as the author of every comment and highlight they add
userIdTheir id, kept on what they add as its creator. Use the same id as sub
groupIdA group in your app, such as a team. What they add belongs to it
email, title, organization, organizationalUnitMore about them, for stamps and signatures. They aren’t written into comments

With Comment, people change and delete only what they added themselves: what has their userId on it. Without a userId, nothing they add is theirs. So give every token a userId, and the same one for the same user.

Which copy they change#

By default, everyone’s changes go into the document itself, and everyone who has it open sees each comment as it’s made. That’s right for a team reviewing a contract together.

To give someone a copy of their own, name a layer for them. Their changes go into that layer, on top of the document, and nobody else sees them:

const { token } = await cloudpdf.tokens.issue({
  tenantId,
  body: {
    kind: 'doc',
    docId: application.formId,
    sub: user.id,
    identity: { userId: user.id, displayName: user.name },
    scope: permissions.fillAndSign,
    layerName: `applicant-${user.id}`,
    expiresInSeconds: 3600,
  },
});

Everyone given the same layerName shares that copy. Give one to each applicant filling in a form, or one to each team. A name is up to 256 characters, and names that start with visitor- are kept for grant visitors.

When it runs out#

A token works for expiresInSeconds, from a minute to 90 days. Give the viewer a function instead of a string, and it can get the next one before it runs out, so nobody notices.

The viewer calls the function before each request it makes to CloudPDF. So the function keeps the token it has, and asks your server for the next one only when it’s about to run out. Add PDFs to your app has one to copy.

So keep tokens short: an hour is plenty, since the next one is a request away.

To stop a token before then, revoke it with its jti, which tokens.issue returns with the token. Pass its expiresAt too. Without it, the revocation lapses after 30 days:

const { token, jti, expiresAt } = await cloudpdf.tokens.issue({ … });
 
await cloudpdf.tokens.revoke({ tenantId, jti, expiresAt });

Within a minute, the token stops working, in viewers that have it open too. Revoking needs an API key with Viewer tokens on.

Good to know#

  • A token is for one document. To show a user three documents, make three tokens. Each one is a single request to CloudPDF, and fast.
  • Check before you make one. The token route is where your app decides who may see what. A route that makes a token for any docId it’s given lets anyone open any document.
  • Tokens for uploads, too. An upload token lets a user’s browser upload a PDF straight to CloudPDF: Uploads from the browser.
  • Every language. The SDK is the same in Python, PHP, C#, Go, Java and Ruby: Issue a token.