Skip to content
Docs

Guides

LMS Integration

Connect Moodle, Canvas or any LMS to GroutApp and GroutCode: roster sync and gradebook write-back on one institution API.

View as Markdown

Grout integrates with a learning management system through two jobs. Each one is a small piece of code on your side, uses its own API key, and can be adopted independently.

JobWhat it doesScopesGuide
Roster syncMirrors students, faculty and sections from your SIS or LMS into Groutstudents:write, faculty:write, groups:writeRoster Sync
Gradebook write-backexam.graded webhooks push scores into the LMS gradebooksubmissions:read, webhooks:writeGradebook Sync

There is no LMS plugin to install. Everything runs over plain HTTPS and JSON against https://serverless.grout.app/v1, so the same code works for Moodle, Canvas, Blackboard, a homegrown portal or an LTI tool.

How the pieces fit#

text
SIS / LMS ──(nightly)──► POST /students, /faculty, /groups ──► Grout institution
Grout grades exam ──(event)──► exam.graded webhook ──► your handler ──► LMS gradebook
  1. Provision people once. Your sync creates each student with student_id set to the SIS id, stores the returned id and login_email, and keeps one Grout group per section. Membership is replaced on every run, so groups never drift. Students sign in to the apps themselves with the login email and a one-time code; pre-map personal_email so the code reaches them on the first try.
  2. Get results back. Exams created through the API are graded in Grout. Subscribe an endpoint to exam.graded, verify the signature, fetch the submission for the authoritative score, and write it to the gradebook item mapped to exam_id.

Platform guides#

Moodle

Web-services roster sync and `core_grades_update_grades` for scores.

Canvas

Sections API and `posted_grade` on assignments.

Roster Sync

The LMS-agnostic algorithm, mappings and safety rules.

Gradebook Sync

Handler sketch, exam-to-item mapping, backfill.

Keys and scopes#

Create one key per job in the portal (Institution → Developers → API keys). A leaked roster key cannot then read submissions, and a gradebook key cannot create people.

text
lms-roster     students:write faculty:write groups:write        600/min
lms-gradebook  submissions:read webhooks:write                   100/min

Every key is bound to your institution. No request accepts an institution_id, so a key can never touch another school's data. See API Keys & Scopes.

Sizing#

A 5 000-student institution syncs within the default 600 requests per minute: POST /students/bulk takes 200 students per call, and PATCH /groups/{id} is one call per section. Webhook deliveries are pushed to you, so gradebook write-back costs nothing against the limit beyond one GET /submissions/{id} per graded attempt.

Checklist before go-live#

  • GET /v1/me with each key shows exactly the scopes above.
  • Roster sync stores id and login_email from the API response, never derives them.
  • Webhook handler verifies X-Grout-Signature, acks within 10 seconds, and dedupes on the event id.
  • A test exam assigned to a test group produces a grade in the LMS end to end.
  • Suspend, don't delete, students who leave.

Read Integration Best Practices next: idempotency, backoff, secret handling and monitoring for anything that talks to this API.

PreviousRetries & ReplayNextIntegration Best Practices