Dev Mode

What is Dev Mode?

Dev Mode is an embed mode designed for local development and staging: it enables a short-lived, nonce-protected handshake between the parent loader and an iframe-hosted form so you can preview theme changes and test integration without weakening production security.

Who can generate Dev Tokens

Dev Mode is gated by plan. Forge Plus and above (or equivalent enabled plans) can generate dev tokens. Attempting to enable Dev Mode on a lower plan should show a gate in the dashboard and in the UI.

Where to generate a token

Token generation surface (pick one for implementation; document both if you implement both):

1. Dashboard (recommended): Form → Embed → Dev Mode → "Generate dev token" (returns a single-use, time-limited token and UI shows copy button + revoke option).
2. API (advanced): Admin-only endpoint: POST /api/workspaces/:id/dev-tokens(accepts formId, ttl, returns token metadata). Example below.

Dev Token — properties

• Bound to a single formId and workspace.
• Contains a server-signed payload + signature (HMAC or asymmetric) — validated by embed.
• Contains a nonce and exp (expiry).
• Single-session / replay-protected: nonce is recorded client-side and server-side to avoid replay.
• Invalid in production: embed client refuses to accept dev token when NODE_ENV=production.

Token lifecycle

1. Generate: Admin creates token via dashboard or admin API.
2. Deliver: Token is copied to the developer and placed on the parent loader query param or embed config.
3. Handshake: On iframe load the embed client validates token, post a verification message to parent and establishes a session nonce.
4. Use: Parent includes the token when initiating the FORGE_INIT handshake; the embed verifies signature & expiry and replies with a session nonce (FORGE_AUTH_OK).
5. Seal & expire: Token may be single-use or time-limited; reuse or replay results in a rejected handshake.
6. Revoke/Rotate: Tokens can be revoked from the dashboard or via an admin API; revocation should take effect immediately for subsequent attempts.

Example API (FAKE)

Admin-only endpoint example — return shape is illustrative and intentionally fake.

POST /api/workspaces/:workspaceId/dev-tokens
Body:
{
  "formId": "abc-123",
  "ttlSeconds": 600
}

Response (200):
{
  "token": "BASE64URL({"payload":{...},"signature":"..."})",
  "expiresAt": "2026-02-01T12:34:56Z",
  "singleUse": true
}

Step-by-step: Integrate Dev Mode (copy/paste)

1. Generate a token (dashboard / API) — copy it to clipboard.
2. Change your parent page to include the token in the iframe src or embed config:

   // Example (loader):
   const iframeSrc = "https://forge.app/embed/YOUR_FORM_ID?devToken=YOUR_DEV_TOKEN";
   <iframe src={iframeSrc} sandbox="allow-scripts allow-same-origin"></iframe>
   
   // Or using the embed loader:
   Forge.embed({
     target: "#forge-root",
     formId: "YOUR_FORM_ID",
     dev: true,
     devToken: "YOUR_DEV_TOKEN"
   });

3. Open your parent page (localhost or staging). Parent loader must:
   • Post a FORGE_INIT with the same token to the iframe once it loads.
   • Listen for FORGE_AUTH_OK (includes session nonce) before sending theme updates.
4. Theme preview — after auth, parent can send FORGE_THEME_UPDATE messages including the sealed nonce.
5. Revoke — if the token appears in logs or is leaked, revoke it from the dashboard and do a token rotation.

Example token (FAKE)

Copy/paste example (again: fake):

eyJmYXBzIjoiZmFrZV90b2tlbiIsInBheWxvYWQiOnsibm9uY2UiOiJleGFtcGxlX25vbmNlIiwgImZvcm1JZCI6IjEyMyJ9fQ==

NOTE: This is a fake example token. Real tokens are signed, time-limited, and must be generated by your dashboard or admin API.

Troubleshooting

• Dev mode embeds are not allowed in production — you are using a dev token whileNODE_ENV=production. Ensure you only use dev tokens locally.
• FORGE_INIT token mismatch — parent sent a different token than what’s in the iframe URL. Confirm the token is identical in URL & the FORGE_INIT message payload.
• Message dropped due to missing/invalid nonce — auth handshake did not complete or the session nonce was not included. Ensure you wait for FORGE_AUTH_OKbefore sending subsequent messages.
• Token expired or replayed — generate a fresh token and retry; check dashboard for revocation logs.
• Disallowed origin — parent origin is not recognized by the embed loader; ensure the parent origin is within allowed origins (dashboard or workspace CORS list).

When to use Dev Mode

• Local development (localhost)
• Staging / preview environments with restricted access
• Theme and layout iteration where fast feedback is needed