Skip to main content

Embedding Marketplace

You can embed the Integration Marketplace into your application with just a few lines of code, giving your customers a native integration deployment experience. This article details how to embed Prismatic's integration marketplace into your application, including how to authenticate users in Prismatic seamlessly using your existing authentication system.

Installing Prismatic's Marketplace Code#

To embed marketplace, you must include some Prismatic JavaScript code in your client application. You have two choices for how to incorporate that code: you can add a <script> tag to your client, or you can install an NPM package.

Marketplace as a Script Tag#

You can include the Prismatic Marketplace JavaScript code with a <script> HTML tag. To include the script from Prismatic's default app URL, add this snippet:

<script src="https://app.prismatic.io/cdn/marketplace/latest/index.js"></script>

If you white-label Prismatic (i.e. run Prismatic under a domain you own, like https://integrations.my-example-company.com), use that domain instead:

<script src="https://integrations.my-example-company.com/cdn/marketplace/index.js"></script>

Once the script has loaded, prismatic.* functions (described below) are available for you to use.

Marketplace as an NPM Package#

If your application is written in Node.js, you can include Prismatic's JavaScript code as a Node import. Install the Prismatic Marketplace Node.js package from NPM with npm or yarn:

npm install @prismatic-io/marketplace
# or
yarn add @prismatic-io/marketplace

Then, for any page that needs to invoke a prismatic.* function, include the @prismatic-io/marketplace package at the top of the file:

import prismatic from "@prismatic-io/marketplace";
The Embedded Marketplace Requires HTTPS

For security reasons, the embedded marketplace CORS configuration requires that you run your website using HTTPS (not HTTP). That way, you can ensure that a signed JWT - or other private information - won't be compromised. For local development of your application, we recommend enabling HTTPS (if you don't already) and using mkcert to create SSL certificates for yourself.

The command mkcert -install && mkcert localhost will generate an SSL keypair that is valid for https://localhost and can be consumed by most web frameworks.

Initialize the Prismatic Client#

This portion is optional. When Prismatic is embedded in your app, it's presented in an iframe that by default points to Prismatic's application URL (https://app.prismatic.io). If you use a custom white-label domain (something like https://integrations.my-example-company.com), you can point the iframes that you embed your white-label domain instead. To do that, add this snippet of code:

Optional white-label iframe config
prismatic.init({  prismaticUrl: "https://integrations.my-example-company.com",});

Authenticating Users#

One big advantage of embedding the integration marketplace is that users don't need to be assigned an additional set of credentials to remember. They can log in to your application, and you can provide them with an authentication token that allows them to deploy Prismatic integrations. You do this by generating a JSON Web Token (JWT) that is signed by a unique private key that you get from Prismatic. The JWT contains information about the user from your system. When Prismatic is presented a signed JWT, the JWT signature is verified and the user is granted a customer role of Marketplace, which allows them to deploy integrations for their specific customer in Prismatic.

JWT Signing Keys#

Before you can generate a JWT, you will need a valid signing key from Prismatic. Within Prismatic click the Settings link on the left-hand sidebar, and then open the Embedded tab. Click the + Signing Key button.

You will be presented with a private signing key. Store this key somewhere safe - it's the key you'll use to validate that users are authenticated within your application.

Private keys are not stored in Prismatic

Prismatic does not store the private signing key that is generated, and only saves the last 8 characters so you can easily match up a private key you have with one in our system. Instead, we store the corresponding public key to verify signatures of JWTs you send. Save the private key that you generate somewhere safe. If it's ever compromised, or you lose it, you can deactivate old keys and generate a new one.

Create and Sign a JWT#

Now that you have a signing key, you can create and sign a JSON web token (JWT). Your backend API (not your frontend) should generate a JWT for your users, and your frontend client should request a signed JWT from your backend API.

Do your JWT generation on the backend

Generate the JWT tokens on the backend. Baking JWT generation (including the signing key) into your frontend presents a security problem - someone with the signing key could pretend to be anyone.

Most programming languages that APIs are written in have a JWT library for generating tokens - see jwt.io.

The JWT that you generate for a user should have the following properties:

  • The header should indicate that it's HMAC with SHA-256 encrypted, and should read:
    {  "alg": "RS256",  "typ": "JWT"}
  • The payload should provide a unique user ID sub, a signing time (current time) iat, and an expiration time exp, reading something like this:
    {  "sub": "example@email.com",  "iat": 1631676917,  "exp": 1631680517}
  • The hashing algorithm must use the private signing key you downloaded previously.

Here are a couple of code snippets for JavaScript and Python that would create a valid JWT to authenticate a user in Prismatic:

import jsonwebtoken from "jsonwebtoken";
/* This is for illustrative purposes only; Obviously don't hard-code a signing key in your code.*/const signingKey = `-----BEGIN PRIVATE KEY-----MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDP3+OrT0IXqCu4EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEc5R7QVzxgmGRXjPZGPf5huA1-----END PRIVATE KEY-----`;
const currentTime = Math.floor(Date.now() / 1000);
const token = jsonwebtoken.sign(  {    sub: "example@email.com", // Replace with real user's email    iat: currentTime,    exp: currentTime + 60 * 60, // 1 hour from now  },  signingKey, // Store this somewhere safe  { algorithm: "RS256" });

Use the JWT to Authenticate the User#

Now that a user in your application has a signed JWT from the backend, you can authenticate them with the Prismatic library using the prismatic.authenticate() function in your frontend application:

// Some function that fetches the JWT from your API:const token = getJwtToken();
// Functions that yield your organization's ID in Prismatic and// the externalId for the user's customer in Prismatic:const organizationId = getOrganizationId(); // "T3JnYW5pemF0aW9uOmJkYTk3MjM5LThhMmYtNGRiOS05YWIzLTQ0ZjAyODRjNDhlZA=="const customerExternalId = getCustomerId(); // "abc-123"
await prismatic.authenticate({  organizationId,  customerExternalId,  token,});

The organizationId that you provide must match your Organization's ID in Prismatic, and the customerExternalId must match the external ID of one of your customers.

Embed the Integration Marketplace#

Once a user has been authenticated, you can display the integration marketplace to them using the prismatic.showMarketplace() function. The showMarketplace() function takes two optional arguments - whether or not the marketplace should appear as a popover, and if it's not a popover, a selector identifying which element in the DOM to inject an iframe into.

iframe Injection Method#

When showPopover is set to false, an iframe HTML element is injected into an element that you select with the selector argument. The iframe contains the integration marketplace.

For example, if you have a section of your app that reads:

<div id="integration-marketplace-placeholder" style="height:100%">  Loading...</div>

You can inject the integration marketplace iframe into that div, replacing the "Loading..." text, by invoking:

prismatic.showMarketplace({  selector: `#integration-marketplace-placeholder`,  usePopover: false,});

The result is that the integration marketplace appears to be a portion of the rest of your application:

Popover Method#

If you elect to set usePopover to true, a popover will be opened containing the integration marketplace:

prismatic.showMarketplace({  usePopover: true,});

Matching Application Theme#

Embedding uses the light mode theme

The embedded marketplace always takes a light mode theme. When you set up your custom theme, ensure you customize the light mode theme for your customers.

If you have a custom theme set up within Prismatic, the embedded marketplace will reflect that theme: