1. Home
  2. Knowledge Base
  3. Learning Management Systems
  4. Installing in the LMS
  5. Installing Hypothesis in Canvas – LTI 1.3 (Worldwide)
  1. Home
  2. Knowledge Base
  3. Learning Management Systems
  4. Canvas
  5. Installing Hypothesis in Canvas – LTI 1.3 (Worldwide)

Installing Hypothesis in Canvas – LTI 1.3 (Worldwide)

This guide is for schools without specific data residency requirements. For compliance with Canadian data residency requirements please see the Canadian version of this guide.

Who is this guide for?

  • New or existing Hypothesis customers. If you are not yet a customer, please reach out to us here to talk with a member of Education team about using Hypothesis at your school.
  • People with administrator-level access to their institution’s Canvas instance

As a Canvas Admin you can install the app at the Account, Sub-Account, or course level.

Upgrading an existing Hypothesis LTI 1.1 installation

If you are installing Hypothesis for the first time you can skip this section and begin at Create new Hypothesis LTI Key.

When the LTI 1.3 version of Hypothesis is installed at the root, sub-account, or course-level, all previous Hypothesis assignments created with the LTI 1.1 version of the tool at that same install level will use the new version of the tool.

To ensure that these previous Hypothesis assignments will continue to work properly after upgrading, we will need to know the LTI 1.1 consumer key of the previous Hypothesis tools before upgrading. If you have multiple LTI 1.1 installations of Hypothesis, such as with several separate course-level or sub-account installations, we need the consumer keys from each of these instances.

Locate the LTI 1.1 consumer keys

  1. Navigate to the appropriate course, sub-account, or root level where Hypothesis is currently installed
  2. From the left sidebar menu, click Settings, then select the Apps tab
  3. Click the View App Configurations button
  4. From the list of external apps locate Hypothesis
  5. Click the gear icon to the right of Hypothesis and select Edit
  6. In the Edit App window, locate the Consumer Key and copy the string into a temporary note or text document; you will need to refer to it later in the installation process.
    Location of the Consumer Key and Description fields in the Edit App pop-up window
  7. We also recommend adding a note to the Description field indicate that this app is the old LTI 1.1 instance.

Create new Hypothesis LTI Key

1. Navigate to “Admin” > “Developer Keys”, click on the “+Developer Key” button, and select the “+LTI” option

Locations and sequence of buttons to click to add a new LTI key

2. On the Key Settings page configure the following

  • Method
    • Enter URL
    • https://lms.hypothes.is/canvas/1.3/config
  • Key Name
    • Hypothesis
  • Owner Email
    • Enter an appropriate email address
  • Redirect URIs (make sure there are no extra spaces or characters copied and pasted here)
    • https://lms.hypothes.is/lti_launches

Key Settings page with all values filled in

Click the Save button to save the LTI key.

3. Locate the new Hypothesis LTI Key in the list of Developer Keys and do the following

  1. Copy the string of numbers shown in the Details column. This is the Hypothesis Client ID.
  2. Paste the Client ID into a temporary note or text document; you will need to refer to it later in the installation process.
  3. Click the On button located in the State column to enable the Hypothesis LTI key.

Hypothesis LTI Key listing with Client ID and On button shown

Create new Hypothesis API Developer Key

Note: If you have an existing API Developer Key created for the LTI 1.1 Hypothesis tool, you do not create a new key. Instead, make note of the existing API Developer Key’s ID and Key values and skip to step 5 below.

Creating a Hypothesis Developer Key is highly encouraged, and enables the following deeper integrations with Canvas:

  • Access to Canvas Files for documents
  • Integration with Canvas Groups
  • Integration with Canvas Sections

Note that the Hypothesis Developer Key will be tied to the Hypothesis LTI Key. If the Developer Key is ever deleted the old Hypothesis LTI Key will no longer work and a new LTI key will need to be created.

1. From the “Admin” > “Developer Keys” page, click the “+ Developer Key” button, then click “+ API Key”

Location of buttons to add new Developer API key

2. Under Key Settings, enter the following values

  • Key Name:
    • Hypothesis
  • Owner Email:
    • Enter an appropriate email address
  • Redirect URIs (make sure there are no extra spaces or characters copied and pasted here):
    • https://lms.hypothes.is/canvas_oauth_callback
  • Redirect URI (Legacy):
    • leave blank
  • Vendor Code (LTI 2):
    • leave blank
  • Icon URL:
    • https://d242fdlp0qlcia.cloudfront.net/uploads/brand/HypothesisCanvasIcon.png

Key Settings with all values entered

3. (Optional) If your institution enforces Scopes on Developer Keys, configure the following

  1. Click the switch to Enforce Scopes and check the box to select Allow include parameters.
    Enforce Scopes shown on with Allow include parameters checked
  2. Enable the following 9 API endpoints (organized by category):

    • Courses
      • url:GET|/api/v1/courses/:id (3rd endpoint from top)
      • url:GET|/api/v1/courses/:course_id/users/:id (13th endpoint from top)
    • Files
      • url:GET|/api/v1/courses/:course_id/files (1st endpoint)
      • url:GET|/api/v1/courses/:course_id/folders (2nd endpoint from top)
      • url:GET|/api/v1/files/:id/public_url (27th endpoint from top)
    • Group Categories
      • url:GET|/api/v1/courses/:course_id/group_categories (5th endpoint from top)
      • url:GET|/api/v1/group_categories/:group_category_id/groups (9th endpoint from top)
    • Groups
      • url:GET|/api/v1/courses/:course_id/groups (10th endpoint from top)
    • Sections
      • url:GET|/api/v1/courses/:course_id/sections (1st endpoint)
    • Pages
      • url:GET|/api/v1/courses/:course_id/pages  (6th endpoint)
      • url:GET|/api/v1/courses/:course_id/pages/:url_or_id  (8th endpoint)
  3. Click the Save Key button in the lower right corner to finish

4. Locate the new Hypothesis API Developer Key in the list and click the “On” button to enable

Location of On button

5. Make note of the following Hypothesis API Developer Key values

The ID (shown in the Details column) and Key (shown in a pop-up once you click the Show Key button) will correspond to the API Developer Key ID and API Developer Key Secret fields in our form to which you will submit to Hypothesis later in the install process.

Copy both these values to the temporary note or text file used previously.

Locations of API Developer ID and Key

Install the Hypothesis App

1. With the appropriate account, sub-account, or course loaded, navigate to “Settings” > “Apps”, and click on the “View App Configurations” button

Locations and sequence of buttons to click to add a new App

2. Click the “+ App” button

Location of + App button

3. In the “Add App” pop-up window, select and configure the following

  • Configuration Type
    • By Client ID
  • Client ID
    • Refer to the temporary note or text file used previously, and paste in the Client ID copied earlier from the Hypothesis LTI key

Add App pop-up window with By Client ID selected and the Client ID entered

Click the Submit button to continue.

4. Canvas will recognize the Client ID and ask if you would like to install Hypothesis

Add App pop-up asking to install the Hypothesis app

Click the Install button to install Hypothesis.

5. Locate Hypothesis in the list of Apps, click the Gear button at the far right, and select “Deployment ID”

Hypothesis app listed with gear icon and Deployment ID menu item indicated

6. Copy the Hypothesis Deployment ID shown in the pop-up window

Paste this Deployment ID into the same temporary note or text file used previously.

Location of Deployment ID for Hypothesis to copy

Click the Close button to close the pop-up window.

Submit LTI details to Hypothesis to complete registration

1. Gather the text document that you copied LTI values into during the above steps

You should have values for the following:

  • (If upgrading) Previous LTI 1.1 consumer key
  • Client ID
  • API Developer Key ID
  • API Developer Key secret
  • Deployment ID

2. Open our LTI 1.3 / Advantage Registration form

Image of form to submit an LTI 1.3 Advantage installation

3. If upgrading, check the “Migrate from existing LTI 1.1?” box and enter the LTI 1.1 consumer key(s) previously copied from above

Section of LTI 1.3 Registration form with Migrate from existing LTI 1.1? checked and previous consumer key pasted

4. Enter the following values into the form as shown

  • Email
    • Your email address, or another address that you want associated with this registration
    • Enter the web address of your Canvas instance, e.g. https://myschool.instructure.com
  • LMS
    • Select Canvas from the drop-down menu
  • Client ID
    • Enter the Client ID value previously copied from above
  • API Developer Key ID
    • Enter the API Developer Key ID value previously copied from above
  • API Developer Key Secret
    • Enter the API Developer Key Secret value previously copied from above
  • Deployment ID
    • Enter the Deployment ID value previously copied from above

5. Click the “Submit” button to send your LTI info to Hypothesis

We will email the address you provided above when your registration has been processed and Hypothesis is ready to be used. We can’t wait to have you annotating!

Important note: Hypothesis will not be available to use in courses until you have received confirmation that we have processed your LTI instance.

Was this article helpful?

Related Articles

Ask a Question

Send us a support ticket to get more help.
Create a Ticket