Embedded Patterns

Prismatic Embedded

Reference documentation for embedding Prismatic's integration marketplace and workflow builder inside a customer-facing web application.

Core Concepts

Embedding Prismatic means your customers never leave your app to manage integrations. The flow is:

1. Your backend generates a short-lived signed JWT (10 min) authenticating the customer user
2. Your frontend calls prismatic.authenticate({ token }) with that JWT — never sign JWTs on the frontend
3. The frontend calls prismatic.showMarketplace(), prismatic.showWorkflows(), or another screen method to render an embedded iframe

Before the JWT expires, the frontend re-fetches a fresh JWT from your backend and calls prismatic.authenticate({ token }) again. Existing iframes update automatically.

Critical Security Rule

JWT tokens MUST be signed on your backend using your private key. Never expose the private signing key to the frontend. The frontend only receives the signed JWT string from a backend API endpoint.

Signing Keys

Before any embedding can work, your organization needs a signing key. To check or create one:

# Check existing signing keys
prism organization:signing-keys:list --extended --output json

# Generate a new signing key (Prismatic creates the key pair)
prism organization:signing-keys:generate

# OR: import your own key generated with OpenSSL
openssl genrsa -out my-private-key.pem 4096
openssl rsa -in my-private-key.pem -pubout > my-public-key.pub
prism organization:signing-keys:import -p my-public-key.pub

The private key is only shown once at generation time — store it securely (e.g., environment variable or secrets manager). Prismatic only stores the last 8 characters of the public key for identification.

SDK Quick Start

npm install @prismatic-io/embedded

import prismatic from "@prismatic-io/embedded";

// 1. Initialize once on app startup (before authentication)
prismatic.init();

// 2. Authenticate with a JWT fetched from YOUR backend
const { token } = await fetch("/api/integration-token").then(r => r.json());
await prismatic.authenticate({ token });

// 3. Show an embedded screen
prismatic.showMarketplace({ selector: "#integrations-div", usePopover: false });

JWT Required Claims

Every JWT must include these Prismatic-specific fields — standard JWT libraries won't add them automatically:

organization and customer are the most commonly missed fields — they are not standard JWT claims and must be set explicitly.

Minimum valid payload:

{
  "sub": "user-uuid",
  "organization": "T3JnYW5pemF0aW9uOi...",
  "customer": "your-customer-id",
  "iat": 1700000000,
  "exp": 1700000600
}

JWT Token Lifecycle

• Keep token lifetime short: 10 minutes (exp: currentTime + 600)
• Add a small clock-skew buffer: iat: currentTime - 5
• Re-authenticate before expiry: set a timer to fetch a new JWT and call prismatic.authenticate({ token }) again ~1 minute before the token expires
• Existing iframes are updated automatically when prismatic.authenticate is called with a new token

SDK Methods Reference

Phase-Specific References

Load only the references relevant to the current setup step. This keeps context focused.

Step 2: Signing Keys

• references/authentication.md — Signing key setup (generate, import, list)

Step 3: Backend JWT Endpoint

• references/authentication.md — Backend examples for Node.js, Python, Ruby, Go, C#; JWT claims reference

Step 4: Frontend SDK Setup

• references/framework-examples.md — React, Next.js, Vue, Svelte integration patterns with full code
• references/sdk-api.md — Full SDK type definitions, method signatures, ScreenConfiguration

Follow-up Topics (load on demand)

• Theming / dark mode / custom fonts → references/theming-and-i18n.md
• Translations / i18n / phrase keys → references/theming-and-i18n.md
• Marketplace filters, events, setConfigVars, reconfiguring an instance inline → references/marketplace.md
• Workflow builder setup, workflow contexts (automation entry points) → references/workflow-builder.md
• Dashboard, connections, logs, components → references/additional-screens.md
• Custom marketplace UI / GraphQL → references/custom-marketplace-ui.md

All References

Full list for manual lookup:

• references/authentication.md — JWT claims, signing examples for Node.js, Python, Ruby, Go, C#, and re-authentication pattern
• references/sdk-api.md — Full SDK type definitions, ScreenConfiguration, Filters, PrismaticMessageEvent enum
• references/marketplace.md — showMarketplace, filters (simple and advanced), configureInstance, editInstanceConfiguration, events, setConfigVars
• references/workflow-builder.md — showWorkflows, showWorkflow, workflow contexts (createWorkflow, queryWorkflows), key differences from the low-code designer
• references/theming-and-i18n.md — Light/dark mode, custom fonts, loading screen, custom terms, translations
• references/additional-screens.md — showDashboard, showConnections, showComponents, showLogs, common options
• references/custom-marketplace-ui.md — Building a fully custom marketplace with GraphQL, TypeScript types, avatar images, reconfiguring an existing instance inline (editInstanceConfiguration)
• references/framework-examples.md — React, Next.js, Vue, and Svelte integration patterns with full code examples