Skip to content
Docs

Guides

LMS Integration

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

Grout integrates with a learning management system through three 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
SSO launchA button in the LMS opens GroutApp or GroutCode with the student already signed insso:writeSSO Launch
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
LMS button ──(per click)──► POST /sso/tokens ──► launch_url ──► desktop app signed in
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.
  2. Launch from the LMS. When a student clicks, your service mints a single-use token (30–300 s) for their stored login_email and redirects the browser to launch_url. The desktop app opens on the right exam or activity. No codes, no second password.
  3. 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, a URL activity for launch, `core_grades_update_grades` for scores.

Canvas

Sections API, an External URL module item (or LTI 1.3 launch), `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 mint launch tokens, and a launch key cannot read submissions.

text
lms-roster     students:write faculty:write groups:write        600/min
lms-launch     sso: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.
  • Launch tokens are minted per click and never cached.
  • 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