# 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:

```json
{
  "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": "student@studyreel.com",
  "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"
}
```

<table><thead><tr><th width="210">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>messageType</code></td><td>LTI claim type indicating that this is a resource link request</td></tr><tr><td><code>version</code></td><td>Indicating the LTI version being used</td></tr><tr><td><code>resourceLink</code></td><td>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"</td></tr><tr><td><code>iss</code></td><td>StudyReel issuer URL</td></tr><tr><td><code>deployment_id</code></td><td>Unique deployment ID identifying the instance of your tool being used</td></tr><tr><td><code>target_link_uri</code></td><td>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.</td></tr><tr><td><code>role</code></td><td>The role of the user</td></tr><tr><td><code>sub</code></td><td>The unique student ID from StudyReel</td></tr><tr><td><code>given_name</code></td><td>First name of the student</td></tr><tr><td><code>family_name</code></td><td>Family name of the student</td></tr><tr><td><code>nonce</code></td><td>A random string to prevent replay attacks</td></tr><tr><td><code>iat</code></td><td>Issued at time (timestamp)</td></tr><tr><td><code>exp</code></td><td>Expiration time (timestamp)</td></tr><tr><td><code>jti</code></td><td>Unique token identifier</td></tr><tr><td><code>studyreel_grade_math</code></td><td>Math proficiency of a student in terms of grade</td></tr><tr><td><code>studyreel_grade_language</code></td><td>Language proficiency of a student in terms of grade</td></tr><tr><td><code>studyreel_grade_science</code></td><td>Science proficiency of a student in terms of grade</td></tr><tr><td><code>studyreel_grade_reading</code></td><td>Reading proficiency of a student in terms of grade, null indicates no measured proficiency</td></tr><tr><td><code>user_acquisition_source</code></td><td>StudyReel</td></tr><tr><td><code>map_rit_math</code></td><td>MAP Growth Screener assessment’s RIT score for Math</td></tr><tr><td><code>map_rit_language</code></td><td>MAP Growth Screener assessment’s RIT score for Language</td></tr><tr><td><code>map_rit_science</code></td><td>MAP Growth Screener assessment’s RIT score for Science</td></tr><tr><td><code>map_rit_reading</code></td><td>MAP Growth Screener assessment’s RIT score for Reading, null indicates no recorded score</td></tr></tbody></table>

**Expected Response**

{% tabs %}
{% tab title="201" %}

```json
{
  "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"
}
```

{% endtab %}

{% tab title="400" %}

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

{% endtab %}

{% tab title="401" %}

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

{% endtab %}

{% tab title="500" %}

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

{% endtab %}
{% endtabs %}

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://studyreel.gitbook.io/studyreel-docs/getting-started/launch-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.