Mint storefront preview token

​

When to use this

• The Template Designer’s “Live Preview” CTA — mint a token, embed previewUrl into the iframe src
• Any merchant-facing tool that needs a time-bounded preview link to a draft storefront
• Do NOT use this for production publishing — published storefronts don’t need a token

​

Authentication

​

Request

POST /v2/storefront/preview-token

​

Curl example

curl -s -X POST "https://apiv3.droplinked.com/v2/storefront/preview-token" \
  -H "Authorization: Bearer $MERCHANT_JWT" \
  -H "Content-Type: application/json" \
  -d '{"shopId":"66c0fe34a9f1b1d3e1c2b001"}' | jq .

​

Response (200)

{
  "previewToken": "eyJzaG9wSWQiOiI2NmMwZmUzNGE5ZjFiMWQzZTFjMmIwMDEiLCJleHBpcmVzQXQiOiIyMDI2LTA2LTE0VDEyOjM0OjU2LjAwMFoiLCJraW5kIjoic3RvcmVmcm9udC1wcmV2aWV3In0.a1b2c3d4e5f6...",
  "expiresAt": "2026-06-14T12:34:56.000Z",
  "previewUrl": "https://droplinked.io/demo-shop/_preview?token=eyJzaG9wSWQiOiI2NmMw..."
}

​

Field reference

​

Token format

• payload — UTF-8 JSON { shopId: string, expiresAt: ISO-8601 string, kind: "storefront-preview" } then base64url-encoded
• sig — HMAC-SHA-256 of the payload bytes under PREVIEW_TOKEN_SECRET (or JWT_SECRET fallback for dev), then base64url-encoded

import { createHmac } from 'crypto'

function verifyPreviewToken(token: string, secret: string): { shopId: string; expiresAt: Date } | null {
  const [payloadB64, sigB64] = token.split('.')
  if (!payloadB64 || !sigB64) return null

  const expectedSig = createHmac('sha256', secret)
    .update(payloadB64)
    .digest('base64url')
  if (sigB64 !== expectedSig) return null

  const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'))
  if (payload.kind !== 'storefront-preview') return null
  const expiresAt = new Date(payload.expiresAt)
  if (Number.isNaN(expiresAt.getTime()) || expiresAt < new Date()) return null

  return { shopId: payload.shopId, expiresAt }
}

​

Why HMAC over JWT

• JWKS round-trips (no key fetch from a JWKS endpoint at request time)
• Asymmetric key rotation surface (no private/public key pair, no kid)
• Edge-cache invalidation on key rotation
• The full jose library dependency at the storefront edge

​

TTL + rate limiting

• TTL: 10 minutes from mint. Hard-coded constant PREVIEW_TOKEN_TTL_MS in the service.
• Rate limit: not applied at v1. The cross-shop guard limits abuse blast radius to “self-DoS your own preview.” Revisit if cross-merchant abuse signal appears.
• Single chokepoint: all minting goes through PreviewTokenService.mint so audit-log + rotation hooks can be added in one place.

​

Error responses

​

Related

• Get abandoned cart details — sibling merchant-scoped surface
• Platform fees revenue rollup (admin) — sibling admin operator surface
• Trust fabric stats — sibling public read surface