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.
- The workspace owner mints a registration key in Console > Integrations > API keys
with the
integrations:registerscope - andoutcomes:readas well if you will pull outcomes - and gives it to you. The key's secret is shown once. - You register. The integration is created in the key's workspace with status
pending. - 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.
- 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"]
}
| Field | Required | Rule |
|---|---|---|
name | yes | 1-200 characters, not blank. Shown to the approver. |
external_system | yes | A slug: lower-case letters, digits and inner hyphens, 1-64 characters. |
issuer | yes | The 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_uri | yes | https:// with a host, at most 500 characters. |
webhook_url | no | https:// with a host, at most 500 characters. Omit it (or send null) to pull outcomes instead. |
instructor_roles | no | 1-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
| Status | Meaning |
|---|---|
401 / 403 | Bad key, or it lacks integrations:register. |
404 | Status or secret for an integration this key did not register, or one that was rejected. |
409 | The issuer is already registered; or this key has already registered an integration; or the secret was requested while pending, or has already been issued. |
422 | A field broke a rule above; detail says which. |
429 | More 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.