Embedding the Pathway and Assignment Players in Your App

In this article:

• Overview
• Before you start
• How embedding works
• Step 1: Sign an embed token
• Step 2: Build the embed URL
• Step 3: Add the frame to your page
• Step 4: Listen for messages
• What the learner sees
• Reloads and restarts
• Things to keep in mind
• FAQs

Overview

As a SuperPath partner, you can show a learner's Pathway or assignment inside your own web or mobile app, in an iframe. The learner is signed in automatically, without a password, and sees only the Pathway player or the assignment player: no SuperPath menus, account menu or sign-out.

Your server signs a short-lived token for the learner with your partner secret. Your page frames a SuperPath URL carrying that token. SuperPath checks the token, signs the learner in for that frame only, opens the learning, and tells your page what happens through postMessage.

This guide is for developers. It builds on Implementing Auto Login for Partners, which uses the same partner secret and many of the same token claims.

Before you start

You will need:

• Your Partner ID and partner secret. Both are on the Developer tab of Partner Portal → Settings. See How to Manage Your Partner Credentials and Domains.
• Embedding switched on for your partner account, with your sites listed. Contact SuperPath support with the exact origins of the pages that will contain the frame, for example https://app.yourcompany.com. Each must be a full https:// origin: scheme, host and optional port, with no path. Up to 20 can be listed. Until at least one is listed, embedding is off. The current list is shown under Embedded learning on the Developer tab.
• A customer account linked to your partner account, with the learner in it (or automatic user creation turned on, as for auto login).
• The learning already given to the learner. An embed opens a Pathway or assignment the learner already has. It never assigns anything.
• A JWT library on your server, such as jsonwebtoken for Node.js or PyJWT for Python.

How embedding works

1. Your server signs an embed token for the learner and the learning you want to open.
2. Your page sets an iframe's src to /embed/partner/{partnerId} on the customer's SuperPath address, with the token and your page's origin.
3. SuperPath only lets that page be framed by the origins listed for your partner account.
4. SuperPath checks the token, signs the learner in for this frame only, and opens the learning.
5. SuperPath posts superpath:ready to your page. When the learner finishes, it posts superpath:completed. If the session cannot start or has to end, it posts superpath:session-ended with a reason.

Step 1: Sign an embed token

Sign a JWT with your partner secret using HS256, the only algorithm accepted.

Put exp at the top level of the token. The other claims can be at the top level or inside a data object, as with auto login.

Choosing the target:

The id may contain only letters, numbers, - and _, up to 128 characters. If the learner does not have that learning, the embed does not open (reason target_not_found). For compatibility, learningType and learningId from an auto login token are accepted in place of target.

Example, using Node.js and jsonwebtoken:

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    data: {
      email: 'jane@example.com',
      firstName: 'Jane',
      lastName: 'Smith',
      tenantId: 'pznmtt',
      target: { type: 'pathway', id: 'Xy12AbCdEf34GhIjKl56' },
    },
  },
  process.env.SUPERPATH_PARTNER_SECRET,
  { algorithm: 'HS256', expiresIn: '5m' }
);

Sign tokens on your server only. Never ship the partner secret in a mobile app or a web page.

Step 2: Build the embed URL

https://{host}/embed/partner/{partnerId}?t={token}&parentOrigin={origin}

parentOrigin is what SuperPath posts messages to. It must exactly match one of your listed origins, and, in browsers that report it, the page actually framing SuperPath. If it does not match, the learning still opens but your page receives no messages. SuperPath never posts to *.

When the page loads, SuperPath removes the token from the frame's address and sends no referrer.

Step 3: Add the frame to your page

<iframe
  id="superpath-player"
  src="https://app.superpath.io/embed/partner/YOUR_PARTNER_ID?t=TOKEN&parentOrigin=https%3A%2F%2Fapp.yourcompany.com"
  style="width: 100%; height: 100%; border: 0">
</iframe>

Only the /embed/partner/ page can be framed, and only by your listed origins. Every other SuperPath page refuses to load in a frame, so always start a frame from a fresh embed URL.

Step 4: Listen for messages

SuperPath posts messages to your page with window.parent.postMessage. Check that each message comes from the SuperPath host you framed before trusting it.

const SUPERPATH_ORIGIN = 'https://app.superpath.io'; // the {host} you used

window.addEventListener('message', (event) => {
  if (event.origin !== SUPERPATH_ORIGIN || !event.data) return;

  switch (event.data.type) {
    case 'superpath:ready':
      // the learning is open: hide your loading state
      break;
    case 'superpath:completed':
      // record the completion, close the screen, show your next step
      break;
    case 'superpath:session-ended':
      // mint a new token and set the iframe src again, or close the screen
      console.log('SuperPath session ended:', event.data.reason);
      break;
  }
});

Reasons sent with superpath:session-ended:

What the learner sees

• The Pathway player or the assignment player only. There are no SuperPath menus, no breadcrumbs or Back links, no account menu and no sign-out. Notes, comments and discussions still work.
• When a Pathway is finished, the completed page says "You can close this page." instead of offering a way back to SuperPath.
• Links that would leave the player, such as certificates and some downloads or links in the content, open in a new window outside the frame. Pages outside the players show "This page is not available here." with a Back button.
• If the learning cannot be opened, a neutral card says "This learning could not be opened" (or that the link has expired). The learner never sees a SuperPath sign-in form.
• SCORM and MindSmith content opens inside the frame, in the same players learners use in SuperPath.

Reloads and restarts

The embedded session lives only in the frame's memory. It uses no cookies and saves nothing in the browser, so it never affects a normal SuperPath session in the same browser, and it is gone when the frame reloads.

That means you cannot reload the frame in place. To restart, mint a new token and set the iframe's src to a new embed URL. Do this whenever you receive superpath:session-ended with a reason other than unload, or whenever your own screen needs to show the learning again.

An embed token can be used more than once until it expires, so a reload within a few minutes can reuse it, but minting a fresh one each time is simpler and safer.

Things to keep in mind

• Keep tokens short-lived. The maximum is 10 minutes. Five is plenty: the token is only needed while the frame loads.
• The token is in the URL. Use HTTPS everywhere and do not log or store embed URLs.
• Only your listed origins can frame SuperPath. Changes to the list, made by SuperPath support, can take up to 10 minutes to apply.
• Native mobile apps. If your app's WebView loads a page from one of your listed origins that contains the iframe, everything above works. If the WebView loads the embed URL directly, without an iframe, the learning works but there is no parent page, so no messages are sent. A WebView that shows a local file has no origin that can be listed, so host the containing page on your own site.
• New windows. Links that open outside the frame use a new window. In a WebView, make sure new windows are allowed or opened in the system browser, or those links will do nothing.
• Rotating your partner secret stops every embed token signed with the old one. See How to Manage Your Partner Credentials and Domains.

FAQs

Can an embed assign a Pathway to the learner?
No. It only opens learning the learner already has. Assign it first, through SuperPath or the API, and then embed it.

Can I embed My Learning, the Library or an Event?
No. Only the Pathway player and the assignment player can be embedded.

Why am I not receiving any messages?
Check that parentOrigin exactly matches the origin of the page containing the frame, that this origin is listed for your partner account, and that your listener compares event.origin with the SuperPath host you used in the URL.

Do I need a different token for auto login and for embedding?
They are signed the same way with the same secret, but an embed token must have exp no more than 10 minutes ahead and must include target. An auto login token does not have to.

Who do I contact to add a new site?
SuperPath support. Send the full origin, for example https://portal.yourcompany.com.

Updated on: 26/10/2026