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.
| Field | Required | What to enter |
|---|---|---|
name | yes | A human label shown in the console, such as "Faculty LMS" (1-200 characters). |
issuer | yes | The 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_uri | yes | An https:// URL serving your public keys as a JSON Web Key Set. |
external_system | no | A 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_url | no | An https:// URL where outcome events are POSTed. Leave it empty if you will pull outcomes instead. |
config.instructor_roles | no | Which of your role names make a launch an instructor launch. Case-insensitive. Default ["instructor", "teacher", "author", "admin"]. |
config.instructor_workspace_role | no | The 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. |
type | no | The 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. |
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:
| Field | Meaning |
|---|---|
activity_id | The Murmle activity to open, in the same workspace. It must be published before anyone can launch into it. |
external_resource_id | Your id for the resource - the resource_id claim (up to 200 characters). Linking the same resource again updates the existing link. |
external_context_id | Optional (up to 200 characters). Your course or container id. It is reported back in outcome events as external_context.context_id. |
session_policy | How 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
| Policy | Behaviour |
|---|---|
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. |
shared | One run for the resource, whatever the context: the newest run for the link that is not closed, or a new one. |
per_launch | A 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.
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.