This page offers an overview of the Learnosity grade passback feature, which sends the results of assessments to a Learning Management System (LMS), where it can be processed. The LMS can then run additional scoring functions, such as a grade book or dashboard for reporting.
Grade passback is a mechanism provided by the Learning Tools Interoperability (LTI) specification whereby a Tool Provider (Learnosity in this case) can pass a student's grade back to the Tool Consumer (your LMS or another system that supports LTI). Learnosity supports both LTI 1.1 (Basic Outcomes) and LTI 1.3 (Assignment and Grade Services).
Learnosity LTI implements grade passback in such a way that it can also be considered an acknowledgement or notification that the session has been successfully processed by Learnosity.
Who would need grade passback?
Clients who use a Learning Management System (LMS), such as Canvas, Blackboard, Moodle, or Brightspace.
Why would you need grade passback?
Grade passback is useful because, when you use Learnosity with an LMS, Learnosity runs its own scoring and reporting/analytics routines by default. It does not natively send grades to the LMS for processing.
How is grade passback enabled?
Items API can be initialized so that it will automatically send results back to the platform using LTI grade passback.
The mechanism differs depending on the LTI version in use:
- LTI 1.3 — Learnosity delegates the full Assignment and Grade Services (AGS) flow to a client-hosted endpoint (`grade_passback_url`). Learnosity POSTs the raw score and LTI context to that endpoint; the client's server performs the JWT signing, token exchange, and score submission to the LMS. This keeps your RSA private key on your own infrastructure and credentials never touch Learnosity's systems.
- LTI 1.1 — Learnosity sends an XML message directly to the LMS's Basic Outcomes endpoint, signed with OAuth 1.0a using your LTI key pair created in your Learnosity Console.
What happens when a grade passback fails?
When a grade passback fails for the first time for one session, the passback is retried five times before it is flagged as a failure. This applies to both LTI 1.1 and LTI 1.3.
Technical Implementation Details
Using Items API initialization options
When initializing Items API, pass the grade passback information into the lis_data object. The structure of lis_data differs between LTI versions.
There is more information about selecting a mode of operation on this page: Embedding Learnosity within an LTI Tool Provider.
LTI 1.3 — Assignment and Grade Services (AGS) initialization
The client is responsible for passing any information required by their grade_passback_url endpoint into lis_data at initialization time. Learnosity does not interpret or validate these fields. It forwards them as-is to your endpoint alongside the raw score. The only values Learnosity contributes are data.score and data.max_score, which are calculated from the learner's submitted session. Everything else, such as LMS endpoints, credentials, and identifiers needed to complete the AGS flow, must be supplied by you.
Example initialization JSON containing lis_data:
{
"session_id": "...",
"activity_id": "...",
"user_id": "...",
"type": "submit_practice",
"name": "...",
"config": {},
"lis_data": {
"lti_version": "1.3",
"oauth_consumer_key": "learnosity_lti_key",
"grade_passback_url": "https://your-server.com/lti/grade_passback",
"lineitems": "<AGS lineitems collection URL from LTI launch>",
"token_url": "<LMS OAuth2 token endpoint>",
"token_aud": "<JWT audience claim>",
"client_id": "<LTI 1.3 client ID registered with the LMS>",
"user_id": "<student sub claim from the LTI 1.3 JWT>"
}
}| Attribute | Description |
|---|---|
lti_version*
|
Must be "1.3" — tells Learnosity to use the LTI 1.3 AGS flow. |
oauth_consumer_key*
|
An LTI key from Console - used to authenticate Learnosity's POST to your grade_passback_url via HTTP Basic Auth. |
grade_passback_url*
|
Your HTTPS endpoint that performs the full AGS grade passback (JWT signing, token exchange, score POST to the LMS). |
* Mandatory attribute
The remaining fields (lineitems, token_url, token_aud, client_id, user_id, and any other data your endpoint requires) should be included as additional attributes in lis_data. They will be forwarded as-is to your grade_passback_url alongside the score.
What Learnosity POSTs to your endpoint (LTI 1.3)
Learnosity POSTs JSON to your `grade_passback_url`, authenticated with HTTP Basic Auth using your LTI key pair:
POST https://your-server.com/lti/grade_passback
Authorization: Basic base64(oauth_consumer_key:lti_secret)
Content-Type: application/json
{
"oauth_consumer_key": "learnosity_lti_key",
"lineitems": "https://lms.example.com/.../lineitems",
"token_url": "https://lms.example.com/token",
"token_aud": "https://lms.example.com/auth/token",
"client_id": "your-client-id",
"user_id": "student-123",
"data": {
"score": 8,
"max_score": 10
}
}Your endpoint is responsible for:
- Validating the Basic Auth credentials.
- Signing a JWT client assertion with your RSA private key.
- Exchanging the JWT for an LMS access token.
- Finding or creating the grade column (lineitem) in the LMS.
- POSTing the score to the LMS grading service.
Your endpoint must return HTTP 200, 201, or 204 on success. Learnosity will retry on any other status code.
LTI 1.1 — Basic Outcomes initialization
{
"session_id": "...",
"activity_id": "...",
"user_id": "...",
"type": "submit_practice",
"name": "...",
"config": {
...
},
"lis_data": {
"lis_outcome_service_url": "url_for_grade_passback",
"lis_result_sourcedid": "uniq_resource_user_value"
"oauth_consumer_key": "learnosity_lti_key"
}
}| Attribute | Description |
|---|---|
lis_outcome_service_url*
|
The URL Learnosity will POST the grade to. |
lis_result_sourcedid*
|
A unique identifier for the combination of resource link and user within the LMS grade book. |
oauth_consumer_key*
|
An LTI key from Console. Note, this is not the same as the consumer_keyused to initialize Items API. |
tool_family |
Only required for Canvas — pass "canvas" as the value. |
* Mandatory attribute
One limitation of LTI 1.1 grade passback is that it only permits a single value between 0.0 and 1.0. Learnosity calculates this as the learner's overall percentage score. For example, if an Activity has 10 Questions worth 1 point each and a learner answers 4 correctly, Learnosity will send a score of 0.4.
Sample XML (LTI 1.1)
Learnosity POSTs the following XML to the LMS Basic Outcomes endpoint. The imsx_messageIdentifier is a unique value generated by Learnosity for every POST:
<?xml version="1.0" encoding="UTF-8"?>
<imsx_POXEnvelopeRequest
xmlns="http://www.imsglobal.org/services/ltiv1p1/xsd/imsoms_v1p0">
<imsx_POXHeader>
<imsx_POXRequestHeaderInfo>
<imsx_version>V1.0</imsx_version>
<imsx_messageIdentifier>${messageId}</imsx_messageIdentifier>
</imsx_POXRequestHeaderInfo>
</imsx_POXHeader>
<imsx_POXBody>
<replaceResultRequest>
<resultRecord>
<sourcedGUID>
<sourcedId>${lisResultSourcedId}</sourcedId>
</sourcedGUID>
<result>
<resultScore>
<language>en</language>
<textString>${lisGrade}</textString>
</resultScore>
</result>
</resultRecord>
</replaceResultRequest>
</imsx_POXBody>
</imsx_POXEnvelopeRequest>LTI Keys
LTI keys consist of a key and a secret, much like the standard Learnosity consumer keys used by Items API.
However, LTI keys are not the same as consumer keys. They are linked to a consumer_key, but they can only be used to authenticate with Learnosity's grade passback. This applies to both LTI 1.1 and LTI 1.3.
To generate an LTI key, log in to Console with the administrator User Role and go to Configuration Consumers. From the list of Consumers, select the consumer you are using and open the Authentication Keys tab. Click Create LTI key to create or generate a new one.
This means you can provide an LTI key pair to a third-party LMS to deliver grade passback without exposing your main consumer credentials or granting access to other Learnosity APIs such as the Data API or the Author API.