Preview Handshake

To ensure that drafts and private pages are visible only to authorized editors, Pyxis CMS implements a Secure Handshake protocol. This system eliminates the risk of unauthorized access to unpublished content.

The Handshake Flow

The process consists of three distinct steps:

1. Signed URL Generation

When an editor clicks “Preview” in the admin panel, the backend generates a URL pointing to the frontend: {FRONT_URL}/api/preview?path={PATH}&expires={TIMESTAMP}&signature={HMAC}

• path: Full page path (slug).
• expires: Unix timestamp (valid for 30 minutes).
• signature: HMAC-SHA256 hash of path and expires, signed with the backend’s APP_KEY.

2. Verification Request (Server-Side)

The frontend receives the URL parameters and must send them back to the Laravel API for verification. This must happen server-side (SSR), preferably via the internal Docker network.

Endpoint: GET /api/preview/verify

Query Parameters:

• path, expires, signature (passed from the original URL).

Response (Success - 200 OK):

{
    "valid": true,
    "preview_token": "eyJpdiI6Ilp..."
}

3. Authorized Session (X-Pyxis-Preview)

Upon receiving the preview_token, the frontend stores it in a cookie (httpOnly). For every subsequent data fetch, the frontend must include the header: X-Pyxis-Preview: {PREVIEW_TOKEN}

---

Backend Logic

When the API receives a request with the X-Pyxis-Preview header:

1. Decryption: Validates the token using the private key.
2. Bypass: If valid, the API ignores publication status and serves data from content_draft instead of content.
3. Flag: The response includes is_preview: true, allowing the frontend to display a “Preview Mode” bar.