Web SDK vs. DWS Viewer API: Which key do I use?

A Could not decode license key error when using a DWS API key in NutrientViewer.load() indicates a product mismatch. DWS Viewer API and Web SDK use different authentication methods.

Identify your product

DWS Viewer API authentication

DWS Viewer API uses session tokens, not license keys. The API key authenticates your backend to request session tokens:

// ❌ Wrong — API key is not a license key.
NutrientViewer.load({
  container: "#viewer",
  licenseKey: "dws_live_abc123..."  // Error: Could not decode.
});

// ✅ Correct — Use a session token from your backend.
NutrientViewer.load({
  container: "#viewer",
  session: "<session_token_from_backend>"
});

Get a session token by calling the DWS API from your server:

curl -X POST "https://api.nutrient.io/viewer/sessions" \
  -H "Authorization: Bearer dws_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"allowed_documents":[{"document_id":"<document_id>","permissions":["read"]}]}'

For app-provided documents, omit allowed_documents instead:

curl -X POST "https://api.nutrient.io/viewer/sessions" \
  -H "Authorization: Bearer dws_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{}'

The response contains the session token to pass to the frontend. Do not pass your DWS API key to NutrientViewer.load().

Web SDK authentication

Web SDK uses a license key tied to your domain:

NutrientViewer.load({
  container: "#viewer",
  document: "document.pdf",
  licenseKey: "nX5NbnzGFzYhuWTje1LqC8hWYX1jP_WAqka..."
});

Get your license key from the Nutrient Portal(opens in a new tab) under Manage Licenses after registering your domain.

Quick reference

Which product do I need?

Choose DWS Viewer API if

• You want DWS to manage documents for you
• You want DWS Viewer API session authorization for app-provided documents
• Usage-based pricing works for your scale
• You don’t want to run Document Engine yourself

Choose Web SDK if

• Documents stay on your infrastructure
• Client-side rendering is preferred
• Fixed per-domain licensing fits your model

Additional resources

• DWS Viewer API documentation — Session tokens and API reference
• Open PDFs using DWS Viewer API — Frontend integration guide
• Web SDK licensing — Domain registration and license keys
• Ways to use Web SDK — Web SDK deployment options