Skip to content
Jami3D
Developer docs menu

Secure LMS embeds

Play an experience for one signed-in learner from your LMS or hospital system, and get their results back under your own user id.

How it works

A secure embed plays for exactly one learner your system knows. Your backend asks Jami3D for a single-use grant with a secret key, your page hands it to the player, and the player exchanges it when its session starts. The session is paid for by the secret key's account, and everything it records — answers, results, reports, webhooks — carries the learner's id as your system spells it (externalUserId).

  1. Create a secret key (sk_live_…, or sk_test_… while you build) with the sessions capability, and results to read results back. It is shown once: keep it with your backend's other secrets.
  2. Your backend calls POST /v1/viewer-tokens for the learner and the project.
  3. Your page passes viewerToken (and, for a project not public, cardToken) to createPlayer.
  4. Results reach you by webhook as they happen, or from GET /v1/results.

Issue a grant

The grant is single-use and short-lived: ttlSec from 60 to 3600 seconds (600 when absent), exchanged once, when the player starts a session. With it comes a cardToken that lets the player's facade show a private project's title and poster; it can be used again for five minutes.

server/jami3d.ts
import type { V1ViewerTokenResponse } from "@jami3d/protocol/v1";

/**
 * A single-use grant for one learner, from YOUR backend: the secret key never reaches a page.
 * Call it for every session the player starts (the page asks again when a session renews).
 */
export async function grantFor(projectId: string, learnerId: string): Promise<V1ViewerTokenResponse> {
  const response = await fetch("https://api.jami.live/v1/viewer-tokens", {
    method: "POST",
    headers: {
      authorization: `Bearer ${process.env.JAMI3D_SECRET_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({ projectId, externalUserId: learnerId, ttlSec: 600 }),
  });
  if (!response.ok) throw new Error(`Jami3D refused the grant: ${response.status}`);
  return (await response.json()) as V1ViewerTokenResponse;
}

caps narrows what the session may do (playback always; text_ai and voice_ai when absent). The learner's id is printable text up to 200 characters — use your system's opaque id, never an email address or a name.

Play it in your page

Pass functions rather than strings: the player calls viewerToken for every session it starts (a renewed session needs a new grant), and cardToken when it describes the project.

lesson.ts
import { createPlayer } from "jami3d";

// Your backend answers these two with grantFor(…).viewerToken and grantFor(…).cardToken.
const token = (path: string) => () =>
  fetch(path, { method: "POST", credentials: "same-origin" }).then((response) => response.text());

createPlayer("#lesson", {
  projectId: "0199c4a0-0000-7000-8000-0000000000a1",
  viewerToken: token("/jami3d/grant"),
  cardToken: token("/jami3d/card-token"),
  poster: { title: "Hand hygiene" },
});

A secure embed is not bound to a list of origins like a publishable key: the single-use grant is what lets it play, so only pages that can get one from your backend can play it.

Read the results

GET /v1/results lists the results of the sessions your keys minted, newest change first, filtered by learner, project or time; GET /v1/results/{sessionId}/report returns one learner's report as JSON, an HTML page, CSV, a Word document or a workbook. Both need the results capability.

server/results.ts
import type { V1ResultsResponse } from "@jami3d/protocol/v1";

/** One learner's results, newest change first; ask again with `from` to follow changes. */
export async function resultsOf(learnerId: string, from?: string): Promise<V1ResultsResponse> {
  const query = new URLSearchParams({ externalUserId: learnerId });
  if (from !== undefined) query.set("from", from);
  const response = await fetch(`https://api.jami.live/v1/results?${query}`, {
    headers: { authorization: `Bearer ${process.env.JAMI3D_SECRET_KEY}` },
  });
  if (!response.ok) throw new Error(`Jami3D refused the results: ${response.status}`);
  return (await response.json()) as V1ResultsResponse;
}

To follow changes without polling, subscribe a webhook to result.quiz_answered, session.completed and result.retracted: each carries data.session.externalUserId.