Skip to content
Article

Secure Headless CMS Draft Previews: Signed Links and Config Drift

A headless CMS preview link is a security boundary between two systems. Here is the signed-link contract we use, the checks our Next.js site runs, and the deploy gap that made correct links return an empty 404.

TLDR

  • Treat a headless CMS preview link as a security boundary: the CMS signs it, the site verifies it.
  • Sign type, slug, and expiry together with HMAC-SHA256 and compare signatures in constant time.
  • Read drafts with a separate token, not the key used for published content.
  • Fail closed, but use different status codes for preview not configured and link rejected.
  • If your deploy uses a variable allowlist, add new required variables in the same change as the code.

If your CMS and your website are separate systems, the draft preview link is a security boundary. The CMS decides who may see unpublished content, and the website has to trust that decision without ever seeing the CMS's user list. The usual answer is a short-lived signed link plus a separate token for reading drafts. In our experience the signing code is rarely what breaks. Configuration is. A preview can be built correctly and still fail in production because one secret never made it to the server.

This post covers the contract we use between our own CMS and endertech.com, the checks the site runs on every preview request, and the November 2026 failure where correctly signed links returned an empty 404 on the live site.

Why preview needs its own security design

On a traditional CMS, preview is easy. The editor is logged in, and the same application renders the page. In a headless setup the editor works in one system and the page renders in another. The website has no login session to check. If preview is just a query string like ?preview=true, anyone who guesses it can read launches, pricing pages, or case studies before they are approved.

So the website needs answers to three questions on each preview request:

  • Did the CMS actually create this link?

  • Is the link still fresh?

  • Once we agree to show a draft, how do we fetch it without opening draft content to everyone else who calls the public API?

The contract between CMS and site

Our CMS (Ansible, which we built and run) has a Preview on site button. It asks the CMS backend for a signed URL and opens it in the browser. The URL looks like this:

https://endertech.com/api/preview?type=blog&slug=my-draft&exp=<unix seconds>&sig=<lowercase hex>

The signature is an HMAC-SHA256 of the UTF-8 string type:slug:exp, written as lowercase hex. Both systems hold the same signing secret for that environment. The CMS signs. The website verifies. The secret never travels in the link.

Signing type, slug, and exp together matters. If you sign only the slug, someone can reuse a signature with a later expiry. If you leave out the type, a link for a blog draft could open a portfolio draft that shares the slug.

What the site checks, in order

Our Next.js route handler at /api/preview runs these checks before it shows anything:

  1. Is preview configured at all? If either the signing secret or the draft-read token is empty, return an empty 404. Preview is off by default.

  2. Are all four parameters present? Missing type, slug, exp, or sig fails.

  3. Is the type on the allowlist? Only blog and portfolio are accepted.

  4. Is the slug safe? We reject slugs containing slashes or backslashes, and the dot segments . and .., so a slug cannot point the redirect somewhere else.

  5. Is the expiry a whole number in the future? Expired links fail.

  6. Is the signature lowercase hex? Anything else fails before we compare.

  7. Does the signature match? We compute the expected HMAC and compare with Node's timingSafeEqual, which takes the same time whether the first byte or the last byte differs. A normal string comparison can leak how much of a guess was right.

Any failure in steps 2 through 7 returns an empty 401. On success, the handler turns on Next.js Draft Mode (which sets a bypass cookie so cached pages render fresh) and sends a 307 redirect to /blog/{slug}?preview=1 or /portfolio/{slug}?preview=1.

A separate token for reading drafts

The signed link only proves the visitor may preview. The page still has to get the unpublished content from the CMS. For that, the site sends Authorization: Bearer with a dedicated preview token. It is a different credential from the key the site uses for published content.

Keeping them separate limits damage. The published-content key is used on every page render, so more code paths touch it. If it leaks, the attacker gets content that is already public. The draft token is only used inside Draft Mode, and it can be rotated without touching the rest of the site.

Why the error responses are empty

Both failure responses have no body, so a caller learns nothing beyond the status code about which check failed. That keeps probing boring for an attacker. It also makes debugging harder for your own team, which is the story below.

What broke: the link was right, the server was not

In November 2026, Preview on site links for endertech.com opened to a browser "page can't be found" screen. The CMS was producing correctly signed links. The signing and verifying code agreed. The live site was returning the empty 404 from step 1, meaning it believed preview was not configured.

The cause was our deploy pipeline. Our deploy script builds the production environment file from an allowlist, and the allowlist is the list of variable names in .env.example. That is deliberate. It keeps one file as the source of truth and stops stray CI variables from leaking onto the server. But the two preview variables had been set in GitLab CI and never added to .env.example. The script skipped them, so the server never received them, and the route handler correctly treated preview as off.

Two of our own good decisions combined into a confusing failure. Fail-closed preview turned a missing secret into a quiet 404. A strict deploy allowlist turned a missing line in an example file into a missing secret. The fix, committed on November 12, 2026, was small: add both variable names (with empty values) to .env.example, document the contract, and redeploy staging and production so the servers picked them up.

The most useful line we added to our docs was this one: if you see an empty 404, do not change the CMS link format. An empty 404 means the site is missing preview configuration. An empty 401 means the link itself is bad or expired.

Lessons you can reuse

Ship the variable name with the code that reads it

If your deploy uses any kind of allowlist, whether an example env file, a Helm values schema, or a secrets manifest, adding a new required variable is part of the feature. Put it in the same change as the code that reads it. Reviewers should treat a new process.env read without a matching allowlist entry as a bug.

Make "off" look different from "denied"

Fail closed, but give your own team a way to tell the cases apart. We use 404 for "preview is not configured" and 401 for "this link failed verification." Write down what each status means next to the link format, so nobody "fixes" a working CMS link while chasing a server problem.

Keep a one-line local check

Our docs include a curl command that requests a locally signed preview URL. With both secrets set, the expected result is a 307 to the preview page. Without them, an empty 404. Running both cases takes a minute and catches most setup mistakes before deploy.

Match secrets per environment

The CMS and the site must share the same signing secret and draft token for each environment: staging with staging, production with production. A staging CMS signing links for the production site will fail verification every time, and with empty responses, that looks the same as an expired link.

Remember that adding a variable is not deploying it

Our helper that creates GitLab CI variables from .env.example only creates missing keys and never overwrites existing ones. After adding the names, someone still has to paste the real values in GitLab and redeploy. Put that step in the runbook, not in someone's memory.

When this is more than you need

If your CMS hosts its own preview, or only a few trusted people can reach a password-protected staging site, a signed-link handoff may be extra work for little gain. It earns its place when the public website renders drafts, when editors share preview links with reviewers outside the CMS, or when draft content is sensitive.

How we know and limits

How we know: This is based on our own preview setup between the Ansible CMS and endertech.com (Next.js App Router, deployed through GitLab CI/CD), the route handler and signing code in that repository, and the fix and documentation committed in November 2026. Next.js behavior is from the current Next.js draftMode reference.

Limits: We describe one CMS, one frontend framework, and one deploy pipeline. Hosted platforms such as Vercel or Netlify manage environment variables differently, and many commercial headless CMS products ship their own preview integrations. We did not measure attack attempts or editor time saved, so this post makes no claims about either.

Sources

If your team is planning a headless CMS or untangling preview and deploy configuration on one you already run, our headless CMS development team can help you design it so it fails safely and tells you why.

Drag to pan. Use +/− or Ctrl/Cmd + scroll to zoom. Pinch to zoom on touch devices.

Drag to pan. Use +/− or Ctrl/Cmd + scroll to zoom. Pinch to zoom on touch devices.