Skip to main content

The launch

The launch token​

A JWT (RFC 7519) in compact JWS form, minted by your server for one launch.

FieldRule
algRS256 or ES256. Nothing else is accepted - in particular never none or an HMAC algorithm.
kidRequired. Must match a key in your JWKS. Murmle caches your keys and refetches when it sees an unknown kid, so you can rotate by publishing the new key before signing with it.

Claims​

ClaimTypeRequiredMeaning
issstringyesYour registered issuer, exactly.
audstringyesThe deployment's launch audience: {MURMLE}, unless the operator configured a different one. A token for another Murmle deployment is refused.
substringyesA stable, opaque id for the person on your platform (up to 255 characters). Never an email address: the identity key is (integration, iss, sub), and email is a display attribute only.
jtistringyesA unique token id (up to 64 characters; a UUID is ideal). Single use - see below.
expnumberyesExpiry, Unix seconds. SHOULD be at most 60 seconds after issue.
iatnumbernoIssued-at, Unix seconds. Checked against the clock if present.
nbfnumbernoNot-before, Unix seconds. Checked if present.
resource_idstringyes*Canonical. Your id for the resource being opened; it must be linked.
context_idstringnoCanonical. Your id for the course or container the resource was opened from. Drives the per_context session policy.
emailstringinstructor: yesThe person's address. Required for an instructor launch (an account is matched or provisioned); optional and unused for a learner. Never treated as verified.
namestringnoDisplay name. Kept only in runs whose privacy mode identifies people, and truncated if longer than the nickname limit.
rolesarray of stringsnoYour role names. A launch is an instructor launch if any role is in the integration's instructor_roles; otherwise it is a learner launch. A single string is read as one role.
return_urlstringnoAn absolute http(s) URL for a "back to your course" link. Any other scheme is dropped.
contract_versionstringno"1". Absent means 1. Any other value is refused.
contextobjectnoLegacy. context.activity_id is an alias of resource_id; context.course_id an alias of context_id.

* resource_id, or its legacy alias context.activity_id, must be present.

Canonical names and legacy aliases. The precedence is fixed: resource_id, then context.activity_id; context_id, then context.course_id. A value counts as present only when it is non-empty. When a canonical claim and its alias disagree, the canonical claim wins. Numbers are accepted and compared as strings. A context that is not a JSON object is ignored. New integrations SHOULD send only the canonical names; the aliases stay accepted for clients that already send them.

Single use. Murmle records each jti when it accepts a token and refuses the same jti again, across every server, until the token has expired. A token that fails a check before that point - signature, audience, issuer, expiry, a missing claim, an unsupported contract_version - is not recorded.

Clock skew. Murmle allows 30 seconds of leeway on exp, nbf and iat by default. Keep both clocks on NTP.

Example payload​

{
"iss": "https://lms.example.org",
"aud": "https://murmle.example.org",
"sub": "u_8f3a2c",
"email": "teacher@example.org",
"name": "Ada Teacher",
"roles": ["instructor"],
"resource_id": "lesson-42",
"context_id": "course-7",
"return_url": "https://lms.example.org/courses/7/lessons/42",
"contract_version": "1",
"jti": "5b1e0a7c-3c3e-4a52-9a43-7f0d1f6d2b9e",
"iat": 1791200000,
"exp": 1791200060
}

What a launch does with it​

  • An instructor gets a Murmle account - matched by your (iss, sub) link, or provisioned from email - and a workspace membership with the configured role. An existing Murmle account with the same email is linked only if it is already an active member of the workspace; otherwise the launch is refused, so a token cannot pull a stranger's account into a workspace.
  • A learner gets no account. They become a participant in the run, and what Murmle records about them depends on the run's privacy mode: their platform identity and name are kept only in an identified run.
  • A launch never counts as a sign-in to Murmle and never verifies an email address.

The launch endpoint​

POST {MURMLE}/api/v1/launch/{system}
Content-Type: application/x-www-form-urlencoded

id_token=<the launch token>
  • Send it as a form POST from the browser, typically a self-submitting form. Never put the token in a URL: a URL reaches browser history, the Referer header and proxy logs.
  • {system} is a label used in Murmle's logs, conventionally your external_system slug. It selects nothing: the integration is decided by the token's verified iss. Any URL-safe slug works except exchange, which is reserved.
  • Launches share the per-address rate limit used for joining by code (30 per minute per address by default). An over-limit request gets 429 with a JSON detail.

A minimal self-submitting form:

<form method="post" action="https://murmle.example.org/api/v1/launch/acme-lms">
<input type="hidden" name="id_token" value="eyJhbGciOiJSUzI1NiIsImtpZCI6...">
<noscript><button type="submit">Continue to Murmle</button></noscript>
</form>
<script>document.forms[0].submit();</script>

On success the response is 303 See Other to {MURMLE}/launch/enter?code=<handoff code>&session=<session id>. The browser follows it with a GET, so a refresh cannot re-post a spent token.

On failure the response is 303 to {MURMLE}/launch/error?reason=<message>, which shows the message to the person. The messages are listed in Errors and versioning.

The exchange step​

The exchange step is Murmle's, not yours. The landing page exchanges the handoff code for a participant credential (POST /api/v1/launch/exchange with {"code": "..."}) and drops the person into the activity. The code is single-use and expires after 60 seconds; the credential it buys is good for that one run only - no account, no other session, no workspace. The exchange also carries your return_url (if it passed the scheme check) and the run's privacy notice, which Murmle shows in its own interface.

Embedding and framing​

Launches are top-level navigations: the form POST replaces the page, or opens in a new tab or window. Murmle's launch, landing and error pages refuse to be framed by another site (Content-Security-Policy: frame-ancestors 'self'), so a launch inside an <iframe> is not supported. This is deliberate: the participant credential lives in first-party browser storage, and Safari and Firefox partition or block storage in third-party frames.

Separately, a run can be embedded by join code on host pages the deployment's operator has allowed. An embedded participant joins by code, not through a launch, so no outcome is reported against one of your users.