embedded-patterns

Name: embedded-patterns
Author: prismatic-io

28stars1forks

How to install embedded-patterns?

prismatic-io/prismatic-skills/embedded-patterns

$npx -y skills add prismatic-io/prismatic-skills --skill embedded-patterns

Installs into the current project.

Summary

Reference documentation for embedding Prismatic's integration marketplace and workflow builder in a web application. Covers JWT authentication, the embedded SDK, marketplace and workflow embedding, theming, i18n, additional screens, and custom marketplace UI. Use when the user as

Files · 1

View on GitHub

SKILL.md

1	# Prismatic Embedded
2
3	Reference documentation for embedding Prismatic's integration marketplace and workflow builder inside a customer-facing web application.
4
5	## Core Concepts
6
7	Embedding Prismatic means your customers never leave your app to manage integrations. The flow is:
8
9	1. Your backend generates a short-lived signed JWT (10 min) authenticating the customer user
10	2. Your frontend calls `prismatic.authenticate({ token })` with that JWT — never sign JWTs on the frontend
11	3. The frontend calls `prismatic.showMarketplace()`, `prismatic.showWorkflows()`, or another screen method to render an embedded iframe
12
13	Before the JWT expires, the frontend re-fetches a fresh JWT from your backend and calls `prismatic.authenticate({ token })` again. Existing iframes update automatically.
14
15	## Critical Security Rule
16
17	JWT tokens MUST be signed on your backend using your private key.
18	Never expose the private signing key to the frontend. The frontend only receives the signed JWT string from a backend API endpoint.
19
20	## Signing Keys
21
22	Before any embedding can work, your organization needs a signing key. To check or create one:
23
24	```bash
25	# Check existing signing keys
26	prism organization:signing-keys:list --extended --output json
27
28	# Generate a new signing key (Prismatic creates the key pair)
29	prism organization:signing-keys:generate
30
31	# OR: import your own key generated with OpenSSL
32	openssl genrsa -out my-private-key.pem 4096
33	openssl rsa -in my-private-key.pem -pubout > my-public-key.pub
34	prism organization:signing-keys:import -p my-public-key.pub
35	```
36
37	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.
38
39	## SDK Quick Start
40
41	```bash
42	npm install @prismatic-io/embedded
43	```
44
45	```typescript
46	import prismatic from "@prismatic-io/embedded";
47
48	// 1. Initialize once on app startup (before authentication)
49	prismatic.init();
50
51	// 2. Authenticate with a JWT fetched from YOUR backend
52	const { token } = await fetch("/api/integration-token").then(r => r.json());
53	await prismatic.authenticate({ token });
54
55	// 3. Show an embedded screen
56	prismatic.showMarketplace({ selector: "#integrations-div", usePopover: false });
57	```
58
59	## JWT Required Claims
60
61	Every JWT must include these Prismatic-specific fields — standard JWT libraries won't add them automatically:
62
63	\| Claim \| Required \| Description \|
64	\|-------\|----------\|-------------\|
65	\| `sub` \| Yes \| Unique user ID (UUID or similar) \|
66	\| `organization` \| Yes \| Prismatic organization ID (from org settings → Embedded tab) \|
67	\| `customer` \| Yes \| Your internal customer/tenant ID — identifies which customer this user belongs to \|
68	\| `iat` \| Yes \| Issued-at Unix timestamp. Use `currentTime - 5` to buffer for clock skew \|
69	\| `exp` \| Yes \| Expiry Unix timestamp. Use `currentTime + 600` (10 minutes) \|
70	\| `external_id` \| No \| External ID for this user in Prismatic; typically matches `sub` \|
71	\| `name` \| No \| User's display name \|
72	\| `customer_name` \| No \| If no customer with this `customer` ID exists yet, creates one with this name \|
73	\| `role` \| No \| ULC only: `"admin"` (can deploy) or `"user"` (supplies user config). Defaults to `"admin"`. \|
74
75	`organization` and `customer` are the most commonly missed fields — they are not standard JWT claims and must be set explicitly.
76
77	Minimum valid payload:
78
79	```json
80	{
81	"sub": "user-uuid",
82	"organization": "T3JnYW5pemF0aW9uOi...",
83	"customer": "your-customer-id",
84	"iat": 1700000000,
85	"exp": 1700000600
86	}
87	```
88
89	## JWT Token Lifecycle
90
91	- Keep token lifetime short: 10 minutes (`exp: currentTime + 600`)
92	- Add a small clock-skew buffer: `iat: currentTime - 5`
93	- Re-authenticate before expiry: set a timer to fetch a new JWT and call `prismatic.authenticate({ token })` again ~1 minute before the token expires
94	- Existing iframes are updated automatically when `prismatic.authenticate` is called with a new token
95
96	## SDK Methods Reference
97
98	\| Method \| Purpose \|
99	\|--------\|---------\|
100	\| `prismatic.init(options?)` \| Initialize the SDK (call once at app startup) \|
101	\| `prismatic.authenticate({ token })` \| Authenticate with a signed JWT \|
102	\| `prismatic.showMarketplace(options?)` \| Embed the integration marketplace \|
103	\| `prismatic.showWorkflows(options?)` \| Embed the workflow builder list \|
104	\| `prismatic.showWorkflow({ workflowId, ...options })` \| Open a specific workflow in the builder \|
105	\| `prismatic.createWorkflow(contextStableKey, { name, c

People who liked this also viewed

6 picks

Type

embedded-patterns

28stars1forks

View on GitHub

How to install embedded-patterns?

prismatic-io/prismatic-skills/embedded-patterns

$npx -y skills add prismatic-io/prismatic-skills --skill embedded-patterns

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Prismatic Embedded
2
3	Reference documentation for embedding Prismatic's integration marketplace and workflow builder inside a customer-facing web application.
4
5	## Core Concepts
6
7	Embedding Prismatic means your customers never leave your app to manage integrations. The flow is:
8
9	1. Your backend generates a short-lived signed JWT (10 min) authenticating the customer user
10	2. Your frontend calls `prismatic.authenticate({ token })` with that JWT — never sign JWTs on the frontend
11	3. The frontend calls `prismatic.showMarketplace()`, `prismatic.showWorkflows()`, or another screen method to render an embedded iframe
12
13	Before the JWT expires, the frontend re-fetches a fresh JWT from your backend and calls `prismatic.authenticate({ token })` again. Existing iframes update automatically.
14
15	## Critical Security Rule
16
17	JWT tokens MUST be signed on your backend using your private key.
18	Never expose the private signing key to the frontend. The frontend only receives the signed JWT string from a backend API endpoint.
19
20	## Signing Keys
21
22	Before any embedding can work, your organization needs a signing key. To check or create one:
23
24	```bash
25	# Check existing signing keys
26	prism organization:signing-keys:list --extended --output json
27
28	# Generate a new signing key (Prismatic creates the key pair)
29	prism organization:signing-keys:generate
30
31	# OR: import your own key generated with OpenSSL
32	openssl genrsa -out my-private-key.pem 4096
33	openssl rsa -in my-private-key.pem -pubout > my-public-key.pub
34	prism organization:signing-keys:import -p my-public-key.pub
35	```
36
37	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.
38
39	## SDK Quick Start
40
41	```bash
42	npm install @prismatic-io/embedded
43	```
44
45	```typescript
46	import prismatic from "@prismatic-io/embedded";
47
48	// 1. Initialize once on app startup (before authentication)
49	prismatic.init();
50
51	// 2. Authenticate with a JWT fetched from YOUR backend
52	const { token } = await fetch("/api/integration-token").then(r => r.json());
53	await prismatic.authenticate({ token });
54
55	// 3. Show an embedded screen
56	prismatic.showMarketplace({ selector: "#integrations-div", usePopover: false });
57	```
58
59	## JWT Required Claims
60
61	Every JWT must include these Prismatic-specific fields — standard JWT libraries won't add them automatically:
62
63	\| Claim \| Required \| Description \|
64	\|-------\|----------\|-------------\|
65	\| `sub` \| Yes \| Unique user ID (UUID or similar) \|
66	\| `organization` \| Yes \| Prismatic organization ID (from org settings → Embedded tab) \|
67	\| `customer` \| Yes \| Your internal customer/tenant ID — identifies which customer this user belongs to \|
68	\| `iat` \| Yes \| Issued-at Unix timestamp. Use `currentTime - 5` to buffer for clock skew \|
69	\| `exp` \| Yes \| Expiry Unix timestamp. Use `currentTime + 600` (10 minutes) \|
70	\| `external_id` \| No \| External ID for this user in Prismatic; typically matches `sub` \|
71	\| `name` \| No \| User's display name \|
72	\| `customer_name` \| No \| If no customer with this `customer` ID exists yet, creates one with this name \|
73	\| `role` \| No \| ULC only: `"admin"` (can deploy) or `"user"` (supplies user config). Defaults to `"admin"`. \|
74
75	`organization` and `customer` are the most commonly missed fields — they are not standard JWT claims and must be set explicitly.
76
77	Minimum valid payload:
78
79	```json
80	{
81	"sub": "user-uuid",
82	"organization": "T3JnYW5pemF0aW9uOi...",
83	"customer": "your-customer-id",
84	"iat": 1700000000,
85	"exp": 1700000600
86	}
87	```
88
89	## JWT Token Lifecycle
90
91	- Keep token lifetime short: 10 minutes (`exp: currentTime + 600`)
92	- Add a small clock-skew buffer: `iat: currentTime - 5`
93	- Re-authenticate before expiry: set a timer to fetch a new JWT and call `prismatic.authenticate({ token })` again ~1 minute before the token expires
94	- Existing iframes are updated automatically when `prismatic.authenticate` is called with a new token
95
96	## SDK Methods Reference
97
98	\| Method \| Purpose \|
99	\|--------\|---------\|
100	\| `prismatic.init(options?)` \| Initialize the SDK (call once at app startup) \|
101	\| `prismatic.authenticate({ token })` \| Authenticate with a signed JWT \|
102	\| `prismatic.showMarketplace(options?)` \| Embed the integration marketplace \|
103	\| `prismatic.showWorkflows(options?)` \| Embed the workflow builder list \|
104	\| `prismatic.showWorkflow({ workflowId, ...options })` \| Open a specific workflow in the builder \|
105	\| `prismatic.createWorkflow(contextStableKey, { name, c

People who liked this also viewed

6 picks

Type