Generate a session token

Session tokens used for authentication by DWS Viewer API can be generated using your API key through the POST /viewer/sessions endpoint:

Terminal window
curl -X POST https://api.nutrient.io/viewer/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pdf_live_m1aKhcLgvDBnKjK2X8UL8rhDxuChoGwDFnStimhDGBE" \
  --fail \
  -d '{
      "allowed_documents": [
        {
          "document_id": "<document_id>",
          "document_permissions": [
            "read",
            "write",
            "download"
          ]
        }
      ],
      "exp": 1793769299
    }'
Terminal window
curl -X POST https://api.nutrient.io/viewer/sessions ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer pdf_live_m1aKhcLgvDBnKjK2X8UL8rhDxuChoGwDFnStimhDGBE" ^
  --fail ^
  -d "{\"allowed_documents\": [{\"document_id\": \"<document_id>\", \"document_permissions\": [\"read\", \"write\", \"download\"]}], \"exp\": 1793769299}"
POST https://api.nutrient.io/viewer/sessions HTTP/1.1
Content-Type: application/json
Authorization: Bearer pdf_live_m1aKhcLgvDBnKjK2X8UL8rhDxuChoGwDFnStimhDGBE


{
  "allowed_documents": [
    {
      "document_id": "<document_id>",
      "document_permissions": [
        "read",
        "write",
        "download"
      ]
    }
  ],
  "exp": 1793769299
}

You can then retrieve the session token from the response:

{
  "jwt": "<created_session_token>"
}

Complete integration example

Below is a server-side implementation example showing how to generate a session token for a document:

const express = require("express");


const app = express();
app.use(express.json());


// Generate session token for a document.
app.post("/api/create-session", async (req, res) => {
  try {
    const { documentId } = req.body;
    const apiKey = process.env.NUTRIENT_DWS_VIEWER_API_KEY;


    if (!documentId) {
      return res.status(400).json({
        success: false,
        error: "Document ID is required",
      });
    }


    // Generate session token.
    const sessionPayload = {
      allowed_documents: [
        {
          document_id: documentId,
          document_permissions: ["read", "write", "download"],
        },
      ],
      exp: Math.floor(Date.now() / 1000) + 60 * 60, // 1 hour from now
    };


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


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


    const sessionResult = await sessionResponse.json();


    res.json({
      success: true,
      sessionToken: sessionResult.jwt,
    });
  } catch (error) {
    console.error("Error:", error);
    res.status(500).json({
      success: false,
      error: error.message,
    });
  }
});

Document permissions

When generating session tokens, you can configure the permissions for each document in the document_permissions array. This enables you to control what actions users can perform on the document.

For the complete list of available permissions and their descriptions, refer to the API reference.

Session token expiration

Session tokens expire based on the exp claim, which uses Unix time format (seconds since 1970-01-01T00:00:00Z). By default, session tokens expire in 1 hour if no exp claim is specified.

Next steps

To use session tokens with your documents:

  1. Upload documents — First, upload your documents to DWS to obtain document IDs.
  2. Open in Web SDK — Use the session token to open the document in Nutrient Web SDK.

For a complete server implementation example, refer to the Node.js integration example guide.

Session tokens can be created with additional optional claims to further control their properties. Refer to our API reference for more information.