Note: If you have an existing D2L OAuth 2.0 app already registered for Hypothesis, you do not need to create a new OAuth 2.0 app to take advantage of new features (such as our D2L files integration). You may, however, need to edit and update the OAuth 2.0 scopes configuration. Please see step 3 below for the most current Scope required by Hypothesis. Once your scope has been updated please let us know by clicking the Create a ticket button at the right so we can enable the new features.
Registering a Hypothesis OAuth 2.0 app in D2L allows Hypothesis full integration with D2L groups and D2L file uploads, providing instructors with more flexibility in configuring Hypothesis reading assignments.
Who is this guide for?
- This guide is for D2L administrators who want to register a Hypothesis OAuth 2.0 app with an existing Hypothesis LMS app deployment
- If you are installing the Hypothesis LMS app in D2L for the first time please see our full installation guide here
Register the Hypothesis OAuth 2.0 app
1. From the Admin Tools menu, click on “Manage Extensibility”
2. Select the “OAuth 2.0” tab and click the “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(non-Canada)https://lms.ca.hypothes.is/api/d2l/oauth/callback(🇨🇦 Canada only)
- Scope
content:file:read content:toc:read content:topics:read groups:group:read
- Access Token Lifetime
3600(the default)
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.
4. Copy the following values from the displayed page below:
- Client ID
- Client Secret
Paste these values into a separate temporary note or text document. You will need to supply them to Hypothesis later in the installation process.
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
Locate the existing Hypothesis LTI tool
1. From the Admin Tools menu, click on “External Learning Tools”
a. Select the “LTI Advantage” tab
b. Find and click on the name of the Hypothesis LTI Advantage tool from the list, then scroll to the bottom of the edit page to view the Deployment ID
Copy the Deployment ID value and paste it into the temporary text document used above. Click the Cancel button to close the page.
a. Select the “Manage Tool Providers (Legacy)” tab
b. Find and click on the name of the Hypothesis LTI tool from the list, then in the “Edit Tool Provider” page locate the “Key” field
Copy the Key value and paste it into the temporary text document used above. Click the Cancel button to close the page.
Submit OAuth 2.0 app details to Hypothesis
1. Gather the text document that you copied values into during the above steps
You should have values for the following:
- OAuth 2.0 Client ID
- OAuth 2.0 Client Secret
- LTI Deployment ID/Key
2. Open our D2L OAuth 2.0 App Registration form
4. Enter the following values into the form as shown
- Email
- Your email address, or another address that you want associated with this registration
- LMS URL
- Enter the web address of your D2L instance, e.g. https://myschool.brightspace.com
- 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 / Key
- Enter the LTI Deployment ID or LTI Key value previously copied from above
- Additional notes (optional)
- Include any optional additional notes for the Hypothesis support team
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 the additional Hypothesis D2L integration features such as D2L groups has been turned on.