Skip to main content

Self-service registration

Instead of asking a workspace administrator to enter your details, your platform can register itself. The workspace stays in control: it issues the credential, and it approves the result.

  1. The workspace owner mints a registration key in Console > Integrations > API keys with the integrations:register scope - and outcomes:read as well if you will pull outcomes - and gives it to you. The key's secret is shown once.
  2. You register. The integration is created in the key's workspace with status pending.
  3. An owner or admin approves or rejects it under Console > Integrations > Connected systems, after reviewing your issuer and JWKS URI. Your registration and their decision are all recorded in the workspace's audit log.
  4. You collect your webhook signing secret, once, after approval.

A pending integration can do nothing: its launches are refused ("This integration is not active"), it receives no webhooks, and it has no outcomes to pull. A registration key registers one integration and is then bound to it.

Register​

POST {MURMLE}/api/public/v1/integrations
Authorization: Bearer pk_<prefix>_<secret>
Content-Type: application/json

{
"name": "Acme LMS",
"external_system": "acme-lms",
"issuer": "https://lms.acme.example",
"jwks_uri": "https://lms.acme.example/.well-known/jwks.json",
"webhook_url": "https://lms.acme.example/hooks/murmle",
"instructor_roles": ["instructor", "teaching-assistant"]
}
FieldRequiredRule
nameyes1-200 characters, not blank. Shown to the approver.
external_systemyesA slug: lower-case letters, digits and inner hyphens, 1-64 characters.
issueryesThe exact iss of your tokens. https:// with a host, at most 500 characters; no localhost exception here. A trailing slash is removed. Unique across the deployment.
jwks_uriyeshttps:// with a host, at most 500 characters.
webhook_urlnohttps:// with a host, at most 500 characters. Omit it (or send null) to pull outcomes instead.
instructor_rolesno1-20 role names, each 1-64 characters; stored lower-cased. Omit for the default set.

Any other field is refused with 422 - you cannot set status, type or config yourself.

201 returns your registration (no secret exists yet):

{
"id": "e50557ff-b9f6-443f-8dea-3e02812719ed",
"name": "Acme LMS",
"external_system": "acme-lms",
"issuer": "https://lms.acme.example",
"jwks_uri": "https://lms.acme.example/.well-known/jwks.json",
"webhook_url": "https://lms.acme.example/hooks/murmle",
"instructor_roles": ["instructor", "teaching-assistant"],
"status": "pending",
"signing_secret_issued": false,
"created_at": "2026-10-05T09:00:00+00:00"
}

Check your status​

GET {MURMLE}/api/public/v1/integrations/{id} with the same key returns the same object. Poll it sparingly until status is active. A rejected registration is removed, so the call then returns 404.

Collect the signing secret​

Once status is active:

POST {MURMLE}/api/public/v1/integrations/{id}/signing-secret
Authorization: Bearer pk_<prefix>_<secret>

200 returns {"integration": {...}, "signing_secret": "..."}. This is the only time the secret is shown: it is stored encrypted and never returned again, and a second call is a 409. If you lose it, an owner or admin rotates it and passes the new one to you. Webhooks to your webhook_url start once the secret has been issued. Then ask for your resources to be linked, and launch.

Errors​

StatusMeaning
401 / 403Bad key, or it lacks integrations:register.
404Status or secret for an integration this key did not register, or one that was rejected.
409The issuer is already registered; or this key has already registered an integration; or the secret was requested while pending, or has already been issued.
422A field broke a rule above; detail says which.
429More than 5 registration calls in a minute from this key.

After a rejection the key is unbound, so it could register again; the workspace owner revokes it if that is not wanted. The audit log keeps what the rejected registration claimed to be.