Open app-provided documents in Web SDK

Use this flow when your browser app already has a document and you want DWS Viewer API to authorize the viewer session. The document can come from a local file picker, a URL your app controls, a Blob, an ArrayBuffer, or another source supported by Nutrient Web SDK.

In this app-provided flow, the document isn’t uploaded to DWS as a managed document. Your frontend passes the document and a publishable key or session token to NutrientViewer.load(). To authorize the load, Web SDK sends DWS the credential but never the document.

Use upload documents instead if you want Nutrient infrastructure to store, stream, and manage the document as a DWS-managed document.

A publishable key is safe in browser code and works without a backend. Create one on the API keys page(opens in a new tab) of the DWS dashboard and pass it directly as session. A session token comes from your backend, as shown in the next section.

Recommended: Set Allowed origins for each publishable key. Without allowed origins, the key works on any website, and loads from every site count toward your viewer-session quota.

Create a browser session

On your backend, create a session with POST /viewer/sessions and omit allowed_documents from the request body:

const response = await fetch("https://api.nutrient.io/viewer/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.NUTRIENT_DWS_API_KEY}`,
  },
  body: JSON.stringify({}),
});

if (!response.ok) {
  throw new Error(`Session creation failed: ${response.statusText}`);
}

const { jwt } = await response.json();

Load the document in Web SDK

In the browser, pass the document to NutrientViewer.load(), with the publishable key or session token as session:

await NutrientViewer.load({
  container: "#viewer",
  session: "<session_token>",
  document: "/documents/example.pdf",
});

Omit licenseKey for this flow. The publishable key or session token authorizes the viewer load.

The document option accepts the same input types supported by Web SDK, including URLs, Blobs, ArrayBuffers, Base64 data, and local files selected by the user. For details, refer to the Web SDK open document guides.

Quota behavior

Each app-provided document load consumes one viewer session, drawn from the same monthly viewer-session quota as DWS-managed documents. DWS counts the session when it authorizes the load, so a load still consumes a viewer session if the document then fails to open. Creating a session token doesn’t count, and neither does a load that DWS rejects.

App-provided documents don’t consume DWS document upload, storage, or document-count quota because they aren’t stored as DWS-managed documents.

Offline use and token lifetime

Every viewer load requires a connection to DWS, even with a session token that hasn’t expired. Web SDK doesn’t store the authorization between loads, so it sends the publishable key or session token to DWS every time. Reloading the page, opening the viewer in a new tab, and opening another document each count as a new viewer session.

After it loads, the viewer works without a connection to DWS. Viewing, annotating, editing, and form filling keep working offline until the viewer is unloaded, even after the session token expires. Deleting a publishable key or reaching your viewer-session limit stops new loads but doesn’t affect viewers that are already open. Features that call other servers — such as AI Assistant, your signing service, or your own backend — still require a connection to those servers. The same goes for a large document that’s still downloading from its URL.

The two credentials have different lifetimes:

• Publishable key — Doesn’t expire and works until you delete it.
• Session token — Lasts 1 hour by default, or up to 24 hours if you set exp. DWS checks it only when the viewer loads.

To start the viewer with no connection to Nutrient, use a Web SDK license key and self-host the SDK assets.

DWS-managed documents require a connection to DWS the whole time the viewer is open, because DWS serves their pages and stores their changes.

Limitations

• Publishable keys work only with app-provided documents. To open DWS-managed documents, create a document-bound session token on your backend.
• setSession() isn’t supported for DWS Viewer API document loading when the document is provided by your app.
• The session isn’t refreshed after load. An open viewer keeps working after the session token expires.
• Your app is responsible for controlling access to the document source it passes to Web SDK.

Existing integrations

Existing integrations that already issue DWS Viewer API frontend sessions can also authorize app-provided document loading for compatibility. For new integrations, use a publishable key or create a browser session by omitting allowed_documents.

Troubleshooting

• If session creation fails, check that your backend sends the secret API key and keeps it out of the browser.
• If a publishable key fails with an origin error, check its Allowed origins on the API keys page(opens in a new tab). Add your app’s host, keeping in mind that *.example.com covers subdomains but not example.com itself.
• If loading fails with “the publishable key or session is invalid, expired, or missing”, check the credential. Create a new session token or confirm that the publishable key still exists.
• If loading fails with “failed while connecting to the authorization endpoint: Failed to fetch” or a similar browser error, check that the device is online. If it is, check that your Content Security Policy includes https://api.pspdfkit.com in connect-src.
• If viewer loading fails with a quota or session-limit error, check the DWS dashboard usage for the application.
• If Web SDK asks for a license key, remove licenseKey and make sure both session and document are passed to NutrientViewer.load().