Skip to main content

Registration and linking

Registering your platform​

A workspace owner or admin registers your platform through Murmle's workspace API, POST /api/v1/integrations, signed in as themselves. The console's Integrations page lists the workspace's Connected systems with their status; creating, linking, disabling and rotating are done through the API. If you would rather register yourself and have an owner or admin approve it in the console, see Self-service registration.

Registration is per workspace: one issuer belongs to exactly one workspace, and a token from your issuer can only ever land in that workspace.

FieldRequiredWhat to enter
nameyesA human label shown in the console, such as "Faculty LMS" (1-200 characters).
issueryesThe exact iss your tokens carry. Must be an https:// URL; http://localhost is accepted for local development. A trailing slash is removed when stored, so mint iss without one. Unique across the deployment.
jwks_uriyesAn https:// URL serving your public keys as a JSON Web Key Set.
external_systemnoA short slug naming your product, such as acme-lms (up to 120 characters). Used in run titles and logs only; it changes no behaviour. When omitted it is derived from name.
webhook_urlnoAn https:// URL where outcome events are POSTed. Leave it empty if you will pull outcomes instead.
config.instructor_rolesnoWhich of your role names make a launch an instructor launch. Case-insensitive. Default ["instructor", "teacher", "author", "admin"].
config.instructor_workspace_rolenoThe Murmle workspace role a launched instructor is given: presenter by default (run sessions and read results, not edit other people's activities). An unknown value falls back to presenter. An existing member's role is never changed by a launch.
typenoThe protocol. The only value is generic, meaning this contract, and it is the default. pamba is accepted as a deprecated alias and stored as generic.
note

Murmle's console checks that issuer is HTTPS. Use HTTPS for jwks_uri and webhook_url too: the JWKS is what Murmle trusts your launches against, and outcome events name real people.

On creation Murmle returns a signing secret, exactly once. Store it; it verifies the webhooks you receive. It is stored encrypted and never returned again. An owner or admin can rotate it, which returns the new secret once and invalidates the old one immediately.

An owner or admin can disable an integration at any time (POST /api/v1/integrations/{id}/disable). A disabled integration's launches are refused and its webhooks stop; Murmle's own sign-in is unaffected. Enabling it again (.../enable) restores both. A pending registration can be neither enabled nor disabled; it has to be approved or rejected first.

Linking resources to activities​

A launch names one of your resources - a lesson activity, a module item. An owner or admin links each resource id to a Murmle activity with POST /api/v1/integrations/{integration_id}/links:

FieldMeaning
activity_idThe Murmle activity to open, in the same workspace. It must be published before anyone can launch into it.
external_resource_idYour id for the resource - the resource_id claim (up to 200 characters). Linking the same resource again updates the existing link.
external_context_idOptional (up to 200 characters). Your course or container id. It is reported back in outcome events as external_context.context_id.
session_policyHow launches map onto sessions (runs). See below.

A launch for a resource that is not linked is refused with "That activity is not linked to a Murmle activity yet".

Session policies​

PolicyBehaviour
per_context (default)One run per context_id, so a cohort's answers sit together. A launch reuses the newest run for the link that is not closed and whose title carries the launch's context_id; otherwise a new run is created. A launch without a context_id behaves as shared.
sharedOne run for the resource, whatever the context: the newest run for the link that is not closed, or a new one.
per_launchA fresh run for every launch.

A run created by a launch is titled <external_system> course <context_id> (or <external_system> launch without a context). It takes the privacy mode of the activity's published version - identified by default for a quiz, anonymous to the creator by default for a poll, survey or Q&A - and it is a live run: it opens in the lobby, and a presenter starts it and moves it through its questions from the presenter view.

tip

If you need outcomes for a resource, make sure the activity's creator has kept (or chosen) the identified privacy mode. Anonymous runs produce no submission.completed events - see Outcome events.