The LMS API: Scoped Keys, Least Privilege & Integrations You Can Audit

There are two ways a learning platform can stop being an island. The first is to speak when something happens — a learner enrolls, a grade posts, a certificate is issued — and push that event to whoever is listening. That's webhooks, and we wrote about them in Your LMS Shouldn't Be an Island. The second is to answer when it's asked: who is on this roster right now? what did this cohort score? enroll these forty people I just onboarded. That's the API, and it's the half this post is about.

Push and pull

The distinction matters more than it sounds, because the two solve genuinely different problems. A webhook is the only sane way to react in real time to something you didn't schedule. An API call is the only way to ask a question nobody anticipated, backfill something you missed, or make a change from outside the dashboard.

Most real integrations use both. The webhook wakes your job up; the API call fetches the detail the job needs and writes the result back. Neither one replaces the other, and if you find yourself polling a list endpoint every sixty seconds waiting for something to change, that's the signal you wanted a webhook.

One host, one header

There is no separate API host to remember. The API lives under your own academy's address — the same one your staff sign in at. If your academy's address is https://youracademy.example, every endpoint is relative to that host.

Authentication is one header. Send your key as a bearer token on every request:

curl -H "Authorization: Bearer eg_live_…" https://youracademy.example/api/courses

That's the whole handshake. No OAuth dance, no token exchange, no session to keep alive. Requests and responses are JSON, apart from the downloads that are deliberately not JSON — the gradebook CSV, the transcript PDF, the QTI export.

Two response codes carry the meaning you'll care about while wiring things up. A key that is unknown, malformed, or revoked gets a 401 with one deliberately vague message — the platform won't tell a stranger whether a key exists, so nobody can probe for valid keys. A perfectly good key that lacks the scope for the endpoint it called gets a 403 naming the scope it needed. In practice: 401 means fix the key, 403 means fix the scopes.

Nine scopes, and why read and write are separate

A key is not a password to your academy. It is a named grant, and at the moment you create it you tick exactly which capabilities it carries. Nine scopes are defined today, deliberately split so that reading and writing are never the same permission:

The read/write split is the part worth dwelling on. A nightly job that pulls grades into a warehouse holds grades:read and nothing else. If a bug in that job — or someone who found the key in a log file — tries to enroll a student or invite a user, the call is refused with a 403. Least privilege stops being a policy someone has to remember and becomes a property of the credential.

The scope list is served live from the backend to the key-minting screen, so when a new scope is added it appears in the form without waiting for a release.

What the API actually exposes

Rather than a wall of endpoints, here is the shape of the surface — the things teams typically want, and what each one costs in scopes:

Note the bulk-invite pair: preview is a genuine dry run. You post the list, get back who would be created and who already exists, and nothing is sent until you call commit. Onboarding scripts get to be careful without you writing the safety net yourself.

Four integrations teams actually build

• Provision people from HR. A nightly job reads new joiners out of the HR system, dry-runs the list against invite/bulk/preview, commits the ones that are genuinely new, and enrolls each of them into the classroom their role requires. Two scopes: users:write and enrollments:write. Leavers flow the other way — DELETE /api/users/{id} disables the account rather than erasing the record, so their grades and certificates survive.
• Pull grades into BI. A warehouse job walks the courses it cares about and pulls each gradebook, or takes the CSV export straight into a staging table. One scope, read-only: grades:read. This is the key that most deserves to be narrow, because it is the one that ends up pasted into a scheduler somewhere.
• Issue and file certificates. A compliance workflow checks eligibility, issues the certificate, then downloads the verifiable credential and files it in an external registry. Pair it with the certificate.issued webhook and the registry never drifts from the source of truth — the webhook says something was issued, the API call fetches exactly what.
• Two-way roster sync with an SIS. Read the catalog with courses:read, look up who is eligible with enrollments:read, write the enrollment with enrollments:write, and read the results back with grades:read. Those four scopes are precisely the set a student information system or HR platform needs to close the loop, which is why they exist as separate grants rather than one "integration" toggle.

Minting, rotating, revoking

A credential's life is where most integration incidents are actually won or lost, so it's worth being explicit about all four stages.

• Mint. Keys are created under Settings → API keys, and only by the organization owner — admins and instructors see a notice instead of the list, and the backend enforces the same rule rather than trusting the screen. Give the key a name that says where it will run (Warehouse nightly pull, not key 2); that name is the only clue you get about it later.
• Store. The full secret is shown exactly once, at creation. Only a SHA-256 hash and the first twelve characters are kept, so there is no "show key" button anywhere and no support ticket that can recover it. Copy it into your secret store on the spot.
• Watch. The list shows each key's prefix, its scopes, and when it was last used. The prefix lets you match a line in your logs to a row here without exposing the secret; Last used is the fastest way to find keys nobody needs any more.
• Rotate. Rotation is a deliberate act, and the order matters: mint the replacement, deploy it, confirm the new key's Last used is ticking, then revoke the old one. Two keys can be live at once, so a rotation needs no downtime window.
• Revoke. Revocation takes effect on the next call — there is no cache to wait out. And revoking is not deleting: the row stays, stamped with when it was killed and by whom, because after an incident the question is always "which key was live, and when did we stop it?"

One behavior deserves calling out because it surprises people. A key acts as the account that created it, and it cannot outlive that account: disable the person who minted a key and every key they minted stops working immediately. That's the right default — offboarding shouldn't leave live credentials behind — but it means production integrations should be minted from an account that belongs to the organization, not from whichever owner happened to be at the keyboard that afternoon.

Honest limits

Four things the API doesn't do today, so nobody discovers them at integration time:

• No expiry dates or automatic rotation. Keys live until someone revokes them. Put the rotation in your own calendar — and use Last used as the quarterly cleanup list.
• No separate test key. Every key is an eg_live_ key against your real data. While you're developing, mint a read-only key with the narrowest scope that lets you make progress, and revoke it when you're done.
• No client libraries. There is no SDK to install and none is needed — it's HTTPS and JSON, so whatever HTTP client your stack already has is the integration layer. The curl one-liner above is a complete working example.
• No webhook-write scope. webhooks:read is the only webhook scope — it lets an integration audit your endpoints and their delivery log. Creating and editing webhook subscriptions is a dashboard task for the organization owner.

And the standing advice that outlives any feature list: treat a key like a password, because that's what it is. Grant the minimum scopes, keep it out of source control and log lines, give each integration its own key so you can revoke one without breaking the others, and check the Last used column often enough that a key nobody remembers never sits there quietly working.

FAQ