Issuing from an LMS
What a Moodle, Canvas or Thinkific plugin has to do to issue a credential when somebody finishes a course — and the one mistake that issues the same certificate twice.
Nothing special is needed on our side. An LMS integration is an ordinary API client: it holds an
API key, it watches for a course completion, and it calls POST /v1/credentials. This page is the
whole contract.
The shape of it
Moodle's own badge plugins are a useful measure of how small this is. The open-source
obf-moodle plugin's entire integration surface is six event observers, and one of them —
course_completed — carries most of the value. Everything else is configuration.
So:
- The administrator pastes an API key and picks which credential group each course maps to.
- The plugin subscribes to the LMS's course-completion event.
- On completion it calls
POST /v1/credentialswith the learner's name and email.
The call
POST /v1/credentials
Authorization: Bearer <api key>
Idempotency-Key: course-42-user-917-completion
Content-Type: application/json
{
"templateId": "grp_...",
"recipientEmail": "[email protected]",
"externalRef": "moodle:course=42:user=917",
"values": {
"name": "Priya Raman",
"course_name": "Advanced Statistics",
"completed_on": "2026-11-10"
}
}
values must match the variables the credential group declares. GET /v1/credential-groups lists
them, which is what the plugin's settings screen should read to build its field mapping rather than
asking an administrator to type variable names by hand.
The mistake that issues the same certificate twice
A course-completion event is not fired once.
Moodle re-evaluates completion on a cron schedule, and an administrator who edits a course's
completion criteria, resets a course, or restores it from backup can fire course_completed again
for learners who finished months ago. Canvas and Thinkific have equivalents. A plugin that issues
on every event will issue duplicates — and because publishing consumes a credit and sends an email,
the learner gets a second certificate and the institution gets a second charge.
Two things prevent it, and a plugin should do both:
Send an Idempotency-Key derived from the completion, not from the moment. A key like
course-42-user-917-completion is the same on every retry and on every re-fire. A timestamp or a
UUID per attempt is not an idempotency key — it is a new request each time, which is exactly what
you are trying to avoid.
$key = "course-{$courseid}-user-{$userid}-completion";
Send externalRef too. It is stored as-is and returned on reads, so the plugin can ask us
whether it has already issued for this completion rather than keeping its own ledger and trusting
it.
The two do different jobs. Idempotency-Key protects a single call from being duplicated by a
retry or a re-fire. externalRef lets the plugin reconcile afterwards — after a database
restore, a failed cron run, or a reinstall, when its own record of what it has done may be wrong
and ours is not.
Issue now, publish later
By default POST /v1/credentials issues a credential: the record is written and the document
rendered, no credit is consumed, no email is sent and nothing resolves publicly.
That is usually what an LMS integration wants. Course completion in an LMS is not always final — grades get amended, completions get reversed — and a credential that was emailed to a learner cannot be un-emailed. Letting an administrator review a batch before releasing it costs nothing and is the difference between a correction and an apology.
Release with POST /v1/credentials/{id}/publish when you are ready, or set the credential group to
publish automatically if the completion really is final in your LMS.
Permissions
credentials:issue and credentials:publish are separate permissions, deliberately: whoever
prepares a batch should not necessarily be able to release it. Give the plugin's API key only
credentials:issue unless you intend it to send email without review.
Failures worth handling
| What happened | What you get | What to do |
|---|---|---|
| Out of credits | 402 with error_code: INSUFFICIENT_CREDITS |
Queue and retry; do not drop the completion |
| A value the group does not declare | 400 |
A configuration error — surface it to the administrator, do not retry |
| Rate limited | 429 with Retry-After |
Honour the header |
| We are down | 503 |
Retry with backoff. The completion already happened; the credential can be issued later |
The one that matters is the first. An institution that runs out of credits mid-term should not lose
a month of completions because a plugin treated 402 as a permanent failure.
Webhooks, the other direction
Subscribe to credential.published if the LMS should show the learner their certificate link.
Verify the delivery with the Standard Webhooks headers — any conformant library works. See
webhooks.
About the plugin itself
A Moodle plugin is GPL by construction, so it lives in its own repository and talks to this API like any other integrator. It cannot be distributed inside this platform's codebase, and that is a licensing fact rather than a preference.
Nothing here is Moodle-specific beyond the event name. The same three steps work for Canvas, Thinkific, Docebo or an in-house system.