Grade Passback
Make sure you've read about authenticating API requests before proceeding to the guide below.
The Line Items and Scores endpoints accept both the ltik based and service key based API authentication methods.
The LTI® protocol allows you to manipulate grades in the LMS grade book through the Assignment and Grades service (AGS). A "grade line" — that is, a column in the LMS grade book — is called a line item in LTI® terminology, and a per-user score posted to a line item is called a score. To submit a grade to the LMS, your application needs the id of the relevant line item plus a score object describing the user, their result, and the progress of the activity.
LTIAAS gives you access to the Assignment and Grades service through the /api/lineitems and /api/lineitems/:lineItemID/scores endpoints. The typical pattern is: when a student finishes an activity in your tool, check whether the AGS service is available, locate or create the line item that represents your activity, and submit the score to that line item.
This guide walks through that synchronous pattern. For tools that need to submit grades asynchronously — from cron jobs, webhook handlers, or batch jobs that run long after the original launch — see the Async / Service-Key Grading guide.
A student finishes the activity in your tool
Step 1 of 6The grade-passback flow is initiated by your application, not by the LMS. Your application decides what constitutes "finishing" — submitting a quiz, completing every question, hitting a passing threshold, the teacher manually approving a draft, or a periodic job summarizing nightly progress. LTIAAS does not impose any particular definition of completion; it simply provides the API endpoints to push the resulting grade into the LMS gradebook.
// Inside your "submit attempt" handler
const result = computeScore(attempt) // your application's scoring logic
await sendToLMS(result, ltik, idtoken)
Tracking attempts, retake policies, partial credit, late penalties, and the rules that ultimately produce a final score live entirely inside your application. It's recommended to also design for idempotency from the start, so that re-running the grade-passback step for the same user and activity is safe — the LMS treats subsequent score submissions as updates to the previous one.
What's next
- Launch + idtoken SSO flow — review how a launch identifies the user whose grade is being submitted.
- Deep Linking flow — pre-create line items at deep-link time so that they exist before the student's first launch.
- Async / Service-Key Grading flow — submit grades from cron jobs and background workers using the
serviceKey.
