Live Preview opens your headless frontend for an item (draft or published) from the admin item form. It is not Preview as role (RBAC JSON).

Collection items · Content versioning · Public CMS API · Headless starter · Outbound webhooks

Configure

Collection (edit drawer) → Live Preview URL, or
Settings → Project → Live Preview URL (default) as fallback when the collection field is empty.

Template must be http(s)://… and may include tokens:

Token	Value
`{{id}}`	Item id
`{{slug}}` / `{{collection}}`	Collection slug
`{{locale}}`	Optional content locale (omitted from query when empty)
`{{version}}`	`draft` or `published`
`{{token}}`	Short-lived HMAC preview token (~15 min)

Example:

https://www.example.com/preview/{{collection}}/{{id}}?version={{version}}&token={{token}}

Admin UX

On an existing item, the toolbar Live Preview button (external-link icon) calls GET /collections/{collection}/items/{item}/live-preview-url?version=draft|published (requires can-show-collections) and opens the expanded URL in a new tab.

Requires a configured template (collection or project default). Version follows the Draft/Published workspace when content versioning is on.

Frontend contract

Do not put API keys in the preview URL. Use {{token}}.

Your site should:

Read token (and optional version / locale) from the query
GET {EXTERNA_API_URL}/api/v1/preview?token=…
Render data (same envelope shape as a Public CMS item for published; draft returns the draft_data bag)

curl -sS "http://externa-core.test/api/v1/preview?token=TOKEN" \
  -H 'Accept: application/json'

Response:

{
  "data": {
    "id": 1,
    "collection_id": 3,
    "data": { "title": "…" }
  },
  "meta": {
    "preview": true,
    "version": "draft",
    "locale": "en",
    "expires_at": "2026-09-24T12:00:00Z"
  }
}

Invalid or expired tokens → 403. Missing token → 422.

Security

Tokens are HMAC-signed with APP_KEY and expire quickly. Anyone with a live token can read that item’s preview payload until expiry — treat preview URLs like temporary share links. Rotate APP_KEY only with full awareness of invalidated tokens.

vs Preview as role

	Live Preview	Preview as role
Purpose	Visual frontend	RBAC field visibility (JSON)
Secret	Signed `{{token}}`	Admin session
Audience	Editors + frontend	Admins checking permissions

Next starter

Wire ?token= into externa-next-starter or your app; see Headless starter.