Why Preview Behaves Differently

By Optimizely Education
Published: Mar 11, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Architectural Shift: CMS 13 moves from server-side rendering to Graph-backed, decoupled delivery.
Preview Tokens: Short-lived JWTs that authorize front-end applications to access draft content.
Security Model: Differentiates between public "published" data and private "editor-only" drafts.

The Paradigm Shift: From "In-Process" to "Decoupled"

In legacy versions of Optimizely CMS, the preview experience was straightforward: the CMS and the rendering engine (MVC/Razor) lived in the same process. When an editor clicked a page, the CMS simply loaded the version from the database and rendered it locally. Authentication was handled by the CMS's internal session.

CMS 13 changes the game. In a Graph-backed delivery world, the content your front-end application displays doesn't come directly from the CMS database—it comes from high-performance indexes in Optimizely Graph. This creates an architectural challenge: how do you let a remote application (React, Vue, Next.js) safely see content that hasn't been published yet?

The Core Challenge

Public visitor keys (SingleKeys) in Optimizely Graph are deliberately restricted to Published content only. To view drafts, your application needs a programmatic way to "prove" it has permission to see what editors are currently working on.

Why Tokens Exist: The Security Bridge

Preview tokens are short-lived JSON Web Tokens (JWT) generated by the CMS at the moment an editor opens the Edit view. These tokens act as a "security bridge" between the CMS management interface and your external front-end application.

1. Authorization of Draft Access

When the CMS renders your front-end site inside an iframe (Edit View), it appends a preview_token to the query string. This token contains encrypted claims that tell Optimizely Graph: "This request is on behalf of an authorized editor. Please return the draft version associated with this context."

2. Time-Limited Safety

Unlike persistent API keys, preview tokens typically have a TTL (Time-To-Live) of 5 minutes. This ensures that even if a token were intercepted, it would be useless shortly after, maintaining the integrity of your draft content.

Developer Configuration: Wiring it Up

To enable this behavior, developers must opt-in via the CMS backend. By default, only published content is synced to the public Graph. You must explicitly allow the syncing of draft versions and enable the token generation logic.

Step 1: Enabling Preview Tokens in Startup

// Program.cs or Startup.cs
services.AddContentGraph(options =>
{
    options.EnablePreviewTokens = true; 
});

Step 2: Allowing Draft Sync in appsettings.json

{
  "Optimizely": {
    "ContentGraph": {
      "AllowSyncDraftContent": true
    }
  }
}

How the Frontend Uses the Token

When the front-end application detects the presence of the preview_token parameter, it must swap its authentication header. Instead of using the SingleKey (HMAC), it uses the Bearer Token (JWT).

// Extracting token from URL query string
const urlParams = new URL(window.location.href).searchParams;
const previewToken = urlParams.get('preview_token');

// Injecting into GraphQL Authorization Header
const headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${previewToken}`
};

Key Differences Recap

Legacy CMS: Direct DB connection; browser-based cookie authentication; same-origin process.
CMS 13: Graph index connection; decoupled JWT authorization; cross-origin via communicationinjector.js.

Conclusion

In CMS 13, preview is transformed into a secure, API-driven ritual. The issuing of temporary JWT tokens ensures that remote applications can maintain the high security standards of the platform while providing editors with the real-time, high-fidelity previews they expect. Mastering token-based authorization is the first step in mastering the decoupled architectural model of the modern Optimizely platform.