The launch
The launch token
A JWT (RFC 7519) in compact JWS form, minted by your server for one launch.
Header
| Field | Rule |
|---|---|
alg | RS256 or ES256. Nothing else is accepted - in particular never none or an HMAC algorithm. |
kid | Required. 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
| Claim | Type | Required | Meaning |
|---|---|---|---|
iss | string | yes | Your registered issuer, exactly. |
aud | string | yes | The deployment's launch audience: {MURMLE}, unless the operator configured a different one. A token for another Murmle deployment is refused. |
sub | string | yes | A 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. |
jti | string | yes | A unique token id (up to 64 characters; a UUID is ideal). Single use - see below. |
exp | number | yes | Expiry, Unix seconds. SHOULD be at most 60 seconds after issue. |
iat | number | no | Issued-at, Unix seconds. Checked against the clock if present. |
nbf | number | no | Not-before, Unix seconds. Checked if present. |
resource_id | string | yes* | Canonical. Your id for the resource being opened; it must be linked. |
context_id | string | no | Canonical. Your id for the course or container the resource was opened from. Drives the per_context session policy. |
email | string | instructor: yes | The person's address. Required for an instructor launch (an account is matched or provisioned); optional and unused for a learner. Never treated as verified. |
name | string | no | Display name. Kept only in runs whose privacy mode identifies people, and truncated if longer than the nickname limit. |
roles | array of strings | no | Your 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_url | string | no | An absolute http(s) URL for a "back to your course" link. Any other scheme is dropped. |
contract_version | string | no | "1". Absent means 1. Any other value is refused. |
context | object | no | Legacy. 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 fromemail- 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
Refererheader and proxy logs. {system}is a label used in Murmle's logs, conventionally yourexternal_systemslug. It selects nothing: the integration is decided by the token's verifiediss. Any URL-safe slug works exceptexchange, 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
429with a JSONdetail.
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.