LTI Token Requirements
What Canvas must include in an LTI 1.3 launch token for Humans But Guided to accept and process it.
This covers the claims and scopes required for both student ingestion (linking Canvas students, courses, and assignments to HBG) and grade passback.
Layer 1 — JWT cryptographic validity
| Requirement | Detail |
|---|---|
| Signature valid | Canvas signs the JWT with RS256; HBG fetches the JWKS from Canvas to verify |
| Algorithm | Must be RS256 |
| Not expired | exp claim must be in the future |
| Nonce unused | Replay attack prevention; each nonce is accepted only once |
Layer 2 — LTI registration claims
These bind the token to the specific tool registration created during provisioning.
| Claim | Expected value |
|---|---|
iss | The Canvas instance base URL (e.g. https://canvas.partner.edu) |
aud | The client_id issued when the Developer Key was created |
deployment_id | The deployment ID from the installed tool — must match exactly (e.g. 2:abc..., not a placeholder) |
version | Must be "1.3.0" |
Layer 3 — Message type
| Claim | Expected value |
|---|---|
message_type | "LtiResourceLinkRequest" |
All claims above use the namespace prefix https://purl.imsglobal.org/spec/lti/claim/.
Layer 4 — Identity and context claims
Required to link the launch to the correct student, course, and assignment in HBG.
| Claim | Used for | Required? |
|---|---|---|
sub | Student identifier | Yes |
email | Student email | Optional |
name | Student display name | Optional |
context.id | Course identifier | Yes |
context.label or context.title | Course name | At least one |
resource_link.id | Assignment identifier | Yes |
resource_link.title | Assignment title | Optional |
Layer 5 — Grade passback scopes
These determine whether HBG can post grades back to Canvas after a submission is evaluated.
A launch without AGS claims still succeeds (the student and assignment are registered), but grade passback will be unavailable.
| Claim | Meaning |
|---|---|
endpoint.lineitem | Assignment-specific grade URL (preferred) |
endpoint.lineitems | Course-level grade URL (fallback) |
endpoint.scope | List of granted scopes |
Minimum scope for grade passback:
https://purl.imsglobal.org/spec/lti-ags/scope/scoreRecommended scopes to request in the Developer Key configuration:
https://purl.imsglobal.org/spec/lti-ags/scope/lineitem
https://purl.imsglobal.org/spec/lti-ags/scope/score
https://purl.imsglobal.org/spec/lti-ags/scope/result.readonlyThese correspond to the four gradebook checkboxes in the LTI Advantage Services section of the Developer Key form (see Canvas admin setup).
Outcome matrix
| Scenario | Student registered | Grade passback |
|---|---|---|
All claims present, AGS with score scope | ✅ | ✅ |
All claims present, AGS missing score scope | ✅ | ❌ |
| All claims present, no AGS endpoint | ✅ | ❌ |
Missing context.id or resource_link.id | ❌ | ❌ |
| Signature invalid / expired / wrong issuer | ❌ | ❌ |