Documentation

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:

  1. The administrator pastes an API key and picks which credential group each course maps to.
  2. The plugin subscribes to the LMS's course-completion event.
  3. On completion it calls POST /v1/credentials with 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.