LTI Launch Requests

Signin / Signup Students with LTI Launch Requests

Once your app is registered with StudyReel, you need to prepare to be able to handle LTI launch requests from StudyReel. When a user wants to access your app in StudyReel, we will send an LTI launch request to the Launch URL provided in the tool registration API call. It will be sent as a JSON object and will have all the information required for you to sign up a student to your app if they don’t have an account already, or log them in if they do. This request will be sent each time the user wants to use your app within StudyReel.

This is the request StudyReel will send to your launch URL:

HTTP Method: POST

Endpoint URL: https://myawesometool.com/launch

Launch Request

Headers

Name	Value
Content-Type	application/json

Example body payload:

{
  "messageType": "LtiResourceLinkRequest",
  "version": "1.3.0",
  "resourceLink": {
      "id": "default"
    },
  "iss": "https://studyreel.alpha1edtech.com",
  "deployment_id": "U3BhcnNoJ3MgdGVzdCBhcHAgNjoxLjM=",
  "target_link_uri": "studyreel://learn",
  "role": "Student",
  "sub": "[e-mail]",
  "given_name": "John",
  "family_name": "Doe",
  "nonce": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsd",
  "iat": "2024-09-19 03:14:07",
  "exp": "2024-09-19 04:14:07",
  "jti": "4556",
  "studyreel_grade_math": "5",
  "studyreel_grade_language": "5",
  "studyreel_grade_science": "6",
  "studyreel_grade_reading": "null",
  "age_grade": "5",
  "user_acquisition_source": "StudyReel",
  "map_rit_math": "190",
  "map_rit_language": "170",
  "map_rit_science": "180",
  "map_rit_reading": "null"
}

Name	Description
messageType	LTI claim type indicating that this is a resource link request
version	Indicating the LTI version being used
resourceLink	A unique identifier for the resource, such as a specific assignment or course module; in most cases, it will have a default value, such as "id": "default"
iss	StudyReel issuer URL
deployment_id	Unique deployment ID identifying the instance of your tool being used
target_link_uri	The URL in your app where the student should land after the LTI launch, as specified during LTI registration. By default this will be set to studyreel://learn which will be then replaced by the URL you return.
role	The role of the user
sub	The unique student ID from StudyReel
given_name	First name of the student
family_name	Family name of the student
nonce	A random string to prevent replay attacks
iat	Issued at time (timestamp)
exp	Expiration time (timestamp)
jti	Unique token identifier
studyreel_grade_math	Math proficiency of a student in terms of grade
studyreel_grade_language	Language proficiency of a student in terms of grade
studyreel_grade_science	Science proficiency of a student in terms of grade
studyreel_grade_reading	Reading proficiency of a student in terms of grade, null indicates no measured proficiency
user_acquisition_source	StudyReel
map_rit_math	MAP Growth Screener assessment’s RIT score for Math
map_rit_language	MAP Growth Screener assessment’s RIT score for Language
map_rit_science	MAP Growth Screener assessment’s RIT score for Science
map_rit_reading	MAP Growth Screener assessment’s RIT score for Reading, null indicates no recorded score

Expected Response

201

{
  "status": "success",
  "message": "Student signed up and login token generated.",
  "userID": "students_user_id_in_your_app",
  "userType": "new",
  "loginLink": "https://yourapp.com/learn?token=wew878few7fe8w"
}

400

{
  "status": "error",
  "message": "Invalid request data. Please check the fields."
}

401

{
  "message": "Invalid or missing API key",
  "error": "Unauthorized",
  "statusCode": 401
}

500

{
  "statusCode": 500,
  "message": "Internal server error"
}

Request handling

1. The app should accept the LTI launch request and automatically create a student account if none exists, based on the provided sub and studyreel_grade properties.

2. Roster the student in the appropriate app learning path based on the provided parameters.

3. The app should send a response to Study Reel with a login/magic link with the required parameters to login the student to your app such as login_token.