---
title: "Tokens for your users"
description: "Your server gives each signed-in user a token for the document they open. It says who they are, what they can do, and for how long."
source: "https://www.cloudpdf.com/docs/platform/app/tokens"
---

# 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.

```ts
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](https://www.cloudpdf.com/docs/platform/app/api-keys.md) 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](https://www.cloudpdf.com/docs/platform/grants/permissions.md#in-code) with the dashboard's levels.
[Add PDFs to your app](https://www.cloudpdf.com/docs/platform/quick-start/app.md) 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](https://www.cloudpdf.com/docs/platform/grants/permissions.md), 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:

```ts
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](https://www.cloudpdf.com/docs/platform/quick-start/app.md#5-open-it-in-your-page) 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:

```ts
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](https://www.cloudpdf.com/docs/platform/app/browser-uploads.md).
- **Every language.** The SDK is the same in Python, PHP, C#, Go, Java and Ruby:
  [Issue a token](https://www.cloudpdf.com/docs/api-reference/tokens/issue.md).

* [What people can do](https://www.cloudpdf.com/docs/platform/grants/permissions.md) — The levels and permissions a token's scope takes.
* [What the browser holds](https://www.cloudpdf.com/docs/platform/concepts/security.md) — Why a token in the browser is safe, and what it can't do.
