This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/dws-viewer/developer-guides/generate-a-session-token.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Generate a session token

Generate a session token

Markdown version of this page, suitable for AI agents and automation

Session tokens used for authentication by DWS Viewer API can be generated using your API key through the POST /viewer/sessions endpoint. This is the preferred endpoint for browser viewer sessions in Nutrient Web SDK.

For DWS-managed documents, include allowed_documents to bind the session to one or more documents:

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

Use permissions, not document_permissions.

For app-provided documents, omit allowed_documents:

{}

The following examples show how to generate a DWS-managed document session token using curl and HTTP request formats:

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


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

You can then retrieve the session token from the response. The token is returned in the top-level jwt field:

{
  "jwt": "<created_session_token>"
}

Complete integration example

Below is a server-side implementation example showing how to generate a session token for a DWS-managed 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,
          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 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 DWS-managed 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.

To use session tokens with app-provided documents, create a browser session without allowed_documents and follow the app-provided document guide.

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

If you need separate review state per reviewer, refer to the reviewer-isolated layers guide for a layer-scoped session workflow.

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