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':
| Field | What it says | |
|---|---|---|
docId | Which document | Required |
sub | Who the user is in your app: their id | Required |
scope | What they can do: a level, plus Download, Print or Copy text | Required |
expiresInSeconds | How long the token works: a minute to 90 days | Required |
identity | Their name and details, below | |
origins | The websites the token works on, such as ['https://app.fernquill.example'] | |
layerName | Which copy of the document their changes go into, below |
Who they are#
identity puts a name on what they do:
| Field | What it’s for |
|---|---|
displayName | Their name, shown as the author of every comment and highlight they add |
userId | Their id, kept on what they add as its creator. Use the same id as sub |
groupId | A group in your app, such as a team. What they add belongs to it |
email, title, organization, organizationalUnit | More 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
docIdit’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.