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

Installing Hypothesis in D2L Brightspace – 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 the Education team about using Hypothesis at your school.
  • People with administrator-level access to their institution’s D2L/Brightspace instance

Upgrading an existing Hypothesis LTI 1.1 installation

If you are currently using the LTI 1.1 version of Hypothesis, we recommend that you follow the instructions below to install a new LTI 1.3 version of Hypothesis, and continue to keep this old LTI 1.1 version of the tool in-place, rather than follow D2L’s instructions for migrating the tool to LTI 1.3.

After install, all new Hypothesis reading assignments will default to using the new version of the tool, while any older Hypothesis assignments created using the previous version will continue to use the old tool, resulting in as little disruption as possible.

It is important that you not delete the LTI 1.1 version from D2L, otherwise previous Hypothesis assignments created with the old tool will break.

Register Hypothesis as an LTI Tool

1. From the Admin Tools menu, click on “Manage Extensibility”

Location of Manage Extensibility in D2L Admin Menu

2. Select the “LTI Advantage” tab, and click the “Register Tool” button

Location of Register Tool button

3. Select “Standard” Registration, then enter “Hypothesis” for the Name

Image of Standard Registration selected and Name field filled in

4. Enter the following values in the fields as shown:

  • Domain
    • https://lms.hypothes.is
  • Redirect URIs
    • https://lms.hypothes.is/lti_launches
    • https://lms.hypothes.is/content_item_selection
  • OpenID Connect Login URL
    • https://lms.hypothes.is/lti/1.3/oidc
  • Target Link URI
    • https://lms.hypothes.is/lti_launches
  • Keyset URL
    • https://lms.hypothes.is/lti/1.3/jwks

Screenshot showing the information above entered into the D2L Registration form

5. Make sure the following values are selected and checked

  • Extensions
    • ✓ Assignment and Grade Services
    • ✓ Deep Linking
    • ✓ Names and Role Provisioning Services
  • Roles
    • ✓ Send Institution Role

A screenshot of the D2L tool registration page with the following options checked off: Assignment and Grade Services, Deep Linking, Names and Role Provisioning Services, Send Institution Role.

6. Add the following Substitution Parameters Name : Value combinations

  • ResourceLink.title : $ResourceLink.title
  • ResourceLink.description : $ResourceLink.description
  • ResourceLink.available.startDateTime : $ResourceLink.available.startDateTime
  • ResourceLink.submission.endDateTime : $ResourceLink.submission.endDateTime
  • ResourceLink.id.history : $ResourceLink.id.history
  • Context.id.history : $Context.id.history

Substitution Parameters Name and Value options entered

Leave the Custom Parameters section blank. No custom parameters are needed.

7. Click the “Register” button to register the tool

8. From the “Registration Details” pop-up window, copy the following values

  • Client ID
  • Issuer

Registration Details pop-up window with Client ID and Issuer highlighted

Paste these values into a separate temporary note or text document. You will need to supply them to Hypothesis later in the installation process.

Register a Hypothesis OAuth 2.0 app

Registering a Hypothesis OAuth 2.0 app in D2L allows Hypothesis full integration with D2L groups, providing instructors with more flexibility in configuring group-based Hypothesis reading assignments.

1. From the Admin Tools menu, click on “Manage Extensibility”

Location of Manage Extensibility in D2L Admin Menu

2. Select the “OAuth 2.0” tab and click the “Register an app” button

Location of OAuth 2.0 tab and Register an app button

3. Enter the following values for the fields as shown:

  • Application Name
    • Hypothesis
  • Redirect URI
    • https://lms.hypothes.is/api/d2l/oauth/callback
  • Scope
    • content:file:read content:toc:read content:topics:read groups:group:read
  • Access Token Lifetime
    • 3600 (the default)

Register an Application page with values filled in

Make sure the following check-boxes are selected:

  • ✓ Prompt for user consent
  • ✓ Enable refresh tokens
  • ✓ I accept the Non-Commercial Developer Agreement

Click the Register button to save.

Bottom of Register an App page with check-boxes selected

4. Copy the following values from the displayed page below:

  • Client ID
  • Client Secret

OAuth 2.0 app Client ID and Client Secret values to copy

Paste these values into the same temporary note or text document you used earlier, making sure to differentiate this OAuth 2.0 app Client ID from the LTI Client ID copied earlier.

D2L API Endpoints used by Hypothesis

The following is a list of the D2L API endpoints used by Hypothesis:

  • Retrieve a list of all the group categories for the provided org unit:
    • /d2l/api/lp/(version)/(orgUnitId)/groupcategories/
  • Retrieve a list of all the groups in a particular group category for an org unit:
    • /d2l/api/lp/(version)/(orgUnitId)/groupcategories/(groupCategoryId)/groups/
  • Retrieve the list of available files in a course’s table of contents:
    • /d2l/api/le/(version)/(orgUnitId)/content/toc
  • Retrieve metadata for one individual file:
    • /d2l/api/le/(version)/(orgUnitId)/content/topics/(topicId)
  • Access to the byte stream of one individual file:
    • /d2l/api/le/(version)/(orgUnitId)/content/topics/(topicId)/file

Create a Hypothesis Deployment

1. Open the Admin Tools menu and click on “External Learning Tools”

Location of External Learning Tools from the Admin Tools menu

2. Select the “LTI Advantage” tab, and click the “New Deployment” button

Location of New Deployment button

3. In the Deploy Tool page, select “Hypothesis” from the registered tool drop-down menu

Enter Hypothesis in the Name field, and give it an optional description. Suggested: “Help students read more deeply by engaging in discussions right on top of the content.”

Hypothesis tool selected with Name and Description entered

4. Confirm that the following Extensions are checked

  • ✓ Assignment and Grade Services
  • ✓ Deep Linking
  • ✓ Names and Role Provisioning Services

A screenshot of the extensions from the deployment page in D2L with these checked off: Assignment and Grading Services, Deep Linking, and Names and Role Provisioning Services

5. Under “Security Settings” make sure the following values are selected and checked

  • ✓ Org Unit Information
  • ✓ Name
    • ✓ First Name
    • ✓ Middle Name
    • ✓ Last Name
  • ✓ Email
  • ✓ User ID
  • ✓ Username
  • ✓ Link Information
    • ✓ Title
    • ✓ Description
  • ✓ Classlist including users not known to this deployment

Security Settings options shown configured

6. Under “Configuration Settings” make sure the following values are selected and checked

  • ✓ Open as External Resource
  • ✓ Grades created by LTI will be included in Final Grade
  • ✓ Auto Create Grade Items

Configuration Settings options to be selected

Leave Substitution Parameters and Custom Parameters blank.

7. Click the Add Org Unit button to make the tool provider available to the desired org unit(s)

Locate the appropriate org unit to use, and be sure to select the option to make tool available to All descendants unless you are restricting Hypothesis to the top level org unit only.

Click the Add button.

Org unit and All Descendants selected to add

8. Click the “Create Deployment” button to create the Hypothesis deployment

Location of Create Deployment button

9. From the “Deployment Details” pop-up window, copy the Deployment ID

Brightspace Deployment Details pop-up window with Deployment ID

Paste this value into the same temporary note or text document you used earlier, adding it to the values previously copied.

A screenshot of the D2L

  • Name: Hypothesis Reading
  • URL:
    • Worldwide: https://lms.hypothes.is/content_item_selection
    • 🇨🇦 Canada: https://lms.ca.hypothes.is/content_item_selection
  • Description: Hypothesis-enabled Social Reading
  • Type: Deep Linking Quicklink
  • Width: 800
  • Height: 600

Screenshot of the information above filled into the D2L form

3. Click “Save and Close”

Submit LTI details to Hypothesis to complete registration

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

Registration Details pop-up window with Client ID and Issuer highlightedOAuth 2.0 app Client ID and Client Secret values to copyBrightspace Deployment Details pop-up window with Deployment ID

You will be pasting these values into our form below.

2. Open our LTI 1.3 / Advantage Registration form

Image of form to submit an LTI 1.3 Advantage installation

3. Enter the following values into the form as shown

  • Email
    • Your email address, or another address that you want associated with this registration
  • LMS
    • Select D2L from the drop-down menu
  • LMS URL
    • Enter the Issuer value previously copied from above
  • Client ID
    • Enter the LTI Client ID value previously copied from above
  • OAuth 2.0 Client ID
    • Enter the OAuth 2.0 Client ID value previously copied from above
  • OAuth 2.0 Client Secret
    • Enter the OAuth 2.0 Client Secret value previously copied from above
  • Deployment ID
    • Enter the Deployment ID value previously copied from above

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

Contents