Client authentication and session renewal

When you use Nutrient Web SDK with Document Engine in server-backed mode, the viewer is authenticated with a JSON Web Token (JWT). For short-lived JWTs, you can refresh authentication at runtime without unloading and reloading the viewer.

Runtime JWT refresh API contract

• NutrientViewer.Configuration#onAuthFailed has the signature () => void | Promise<void>.
  • It receives no arguments.
  • Inside this callback, fetch a fresh JWT and call instance.setSession(newJwt).
• NutrientViewer.Instance#setSession has the signature setSession(session: string): void.
  • Pass a raw JWT string.
  • Do not pass { jwt: ... } or an authPayload object.

Reactive refresh: onAuthFailed + setSession

Use this pattern when a request fails due to expired or invalid authentication:

let instance;

instance = await NutrientViewer.load({
  container: "#viewer",
  serverUrl: "https://your-document-engine.example.com",
  documentId: "your-document-id",
  authPayload: { jwt: initialJwt },
  onAuthFailed: async () => {
    const newJwt = await fetchNewJwtFromBackend();
    if (!instance) {
      throw new Error("Viewer instance is not available yet.");
    }

    instance.setSession(newJwt);
  },
});

onAuthFailed is configured at load() time and doesn’t receive the instance. Use a closure or mutable reference (as shown above) so the callback can call setSession on the current instance.

If setSession() isn’t called within 30 seconds while handling an auth failure, the refresh times out and the affected requests fail.

Proactive refresh: Call setSession before expiry

If you know JWT expiry time in advance, refresh before the token expires:

function parseJwtExp(jwt) {
  const [, payload] = jwt.split(".");
  return JSON.parse(atob(payload)).exp;
}

function scheduleJwtRefresh(instance, jwt) {
  const exp = parseJwtExp(jwt);
  const refreshBuffer = 5 * 60 * 1000; // Refresh 5 minutes early.
  const timeout = Math.max(exp * 1000 - Date.now() - refreshBuffer, 0);

  setTimeout(async () => {
    const newJwt = await fetchNewJwtFromBackend();
    instance.setSession(newJwt);

    // Schedule the next proactive refresh.
    scheduleJwtRefresh(instance, newJwt);
  }, timeout);
}

This keeps the same viewer instance alive while rotating session tokens.

Expected behavior during refresh

• If the token refresh succeeds, the current viewer session stays active and document operations continue without reloading the instance.
• If the refresh fails or times out, requests that require authentication fail and the user may need to retry after your app obtains a fresh JWT.

Mode limitations

• This flow is supported only in server-backed mode.
• It isn’t supported when useDeprecatedRestProvider is enabled.
• Calling setSession() in standalone mode is unsupported and only logs a warning.