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:

| Claim | Required | Description | |-------|----------|-------------| | sub | Yes | Unique user ID (UUID or similar) | | organization | Yes | Prismatic organization ID (from org settings → Embedded tab) | | customer | Yes | Your internal customer/tenant ID — identifies which customer this user belongs to | | iat | Yes | Issued-at Unix timestamp. Use currentTime - 5 to buffer for clock skew | | exp | Yes | Expiry Unix timestamp. Use currentTime + 600 (10 minutes) | | external_id | No | External ID for this user in Prismatic; typically matches sub | | name | No | User's display name | | customer_name | No | If no customer with this customer ID exists yet, creates one with this name | | role | No | ULC only: "admin" (can deploy) or "user" (supplies user config). Defaults to "admin". |

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

| Method | Purpose | |--------|---------| | prismatic.init(options?) | Initialize the SDK (call once at app startup) | | prismatic.authenticate({ token }) | Authenticate with a signed JWT | | prismatic.showMarketplace(options?) | Embed the integration marketplace | | prismatic.showWorkflows(options?) | Embed the workflow builder list | | prismatic.showWorkflow({ workflowId, ...options }) | Open a specific workflow in the builder | | prismatic.showDashboard(options?) | Embed the customer dashboard | | prismatic.showConnections(options?) | Embed the connections management screen | | prismatic.showLogs(options?) | Embed the logs screen | | prismatic.showComponents(options?) | Embed the component browser | | prismatic.showComponent({ componentId, ...options }) | Show a specific component | | prismatic.configureInstance(props) | Open a config wizard for an integration | | prismatic.setConfigVars({ iframe, configVars }) | Programmatically set config variables | | prismatic.graphqlRequest({ query, variables? }) | Execute authenticated GraphQL queries |

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 → references/marketplace.md
• Workflow builder setup → 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, events, setConfigVars
• references/workflow-builder.md — showWorkflows, showWorkflow, 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
• references/framework-examples.md — React, Next.js, Vue, and Svelte integration patterns with full code examples