Uploads from the browser
When your users pick a PDF in your app, their browser can upload it straight to CloudPDF. Your server only makes an upload token: it says where the file goes, and it runs out when you say, such as in ten minutes. The file never passes through your server, and your API key never leaves it.
- A user picks a PDF, and your page asks your server for an upload token.
- Your server checks the user may upload, and makes the token with your API key.
- The browser uploads the file with the token, and gets the document back.
- The browser tells your server the document’s id, and your server checks it before keeping it.
Your server can be in any language. The browser code is the same whichever it is.
1. Make an upload token#
In a route your pages call, check that the signed-in user may upload, then make a token:
Node.js
const { token } = await cloudpdf.tokens.issue({
tenantId,
body: {
kind: 'upload',
sub: user.id,
folderId: contractsFolderId,
metadata: { contractId: contract.id },
expiresInSeconds: 600,
},
});Send it back to the page as JSON: { "token": "…" }. The token decides where the file goes and
what it carries. Whatever the browser sends, CloudPDF uses the token’s folder and metadata.
The fields go in body:
| Field | What it says | |
|---|---|---|
kind | 'upload' | Required |
sub | Who is uploading: their id in your app | Required |
expiresInSeconds | How long the token works. Ten minutes is plenty | Required |
folderId | The folder the files go into. Without it, the top level | |
metadata | Your own data, put on every document uploaded with the token, such as { contractId: 'c_381' }. At most 4 KB of JSON | |
maxFiles | How many PDFs the token uploads, up to 1,000. Without it, one | |
maxBytes | The largest file it takes, in bytes | |
origins | The websites the token works on, such as ['https://app.fernquill.example'] |
Your server makes upload tokens with an API key that has Documents and folders on Write. A key hands out only what it can do itself.
2. Upload from the browser#
Install the SDK in your frontend, and import only its upload entry. It’s about 3 KB, and brings nothing else from the SDK:
npm install @cloudpdf/sdkimport { upload } from '@cloudpdf/sdk/upload';
const input = document.querySelector('#contract-pdf');
input.addEventListener('change', async () => {
const response = await fetch(
`/contracts/${contractId}/upload-token`,
{ method: 'POST' },
);
const { token } = await response.json();
const uploaded = await upload(input.files[0], { token });
await fetch(`/contracts/${contractId}/document`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ documentId: uploaded.document.id }),
});
});upload hashes the file, sends it to storage, and has CloudPDF check what arrived. It takes a
File or a Blob, and these options:
| Option | What it does | |
|---|---|---|
token | The upload token from your server | Required |
name | What the dashboard shows. Without it, the file’s name | |
onProgress | Called with (loaded, total) as the bytes go | |
signal | An AbortSignal that stops the upload |
A progress bar, and a button that stops the upload:
const controller = new AbortController();
cancelButton.onclick = () => controller.abort();
const uploaded = await upload(file, {
token,
onProgress: (loaded, total) => {
progressBar.value = loaded / total;
},
signal: controller.signal,
});Without a build step#
A page without a bundler loads the same file from the CDN:
<script type="module">
import { upload } from 'https://cdn.jsdelivr.net/npm/@cloudpdf/sdk@3/dist/esm/upload.mjs';
</script>3. Keep the document#
The browser tells your server which document it uploaded. Don’t take its word for it: look the document up, and check the metadata the token put on it before you keep the id.
Node.js
const { document } = await cloudpdf.documents.get({
tenantId,
docId: documentId,
});
if (document.metadata?.contractId !== contract.id) {
throw new Error('Not uploaded for this contract');
}
await db.contracts.update(contract.id, { documentId: document.id });The browser can’t change that metadata: it came from the token your server made.
What an upload token allows#
An upload token uploads, and nothing else:
- into its folder, with its metadata;
- as many files as
maxFiles, each no larger thanmaxBytes; - until it runs out.
It can’t open, list, rename or delete a document, not even one it uploaded. CloudPDF checks each file against what the browser said it would send, so a file swapped halfway is refused. Copied out of the browser, the token gets someone its own few uploads, for a few minutes.
Good to know#
- Check before you make one. The token route is where your app decides who may upload, and where to. A route that makes a token for anyone lets anyone fill your workspace.
- Every upload counts toward your plan’s uploads this month, from the browser or your server.
- Not a browser? A mobile or desktop app uploads with the same token, through the API: Initialize an upload, send the file, then commit it.