Register a Moodle API Token for an existing Hypothesis LMS app

Note: If you have an existing Moodle integration already registered for Hypothesis, you do not need to create a new integration to take advantage of new features (such as our Moodle files, folders, groups and pages integration). You just have to generate and register an API token that will unlock these new features.

In addition, you can enable the Deep Linking option for the Hypothesis LMS app which will provide an experience where using an external LTI tool like Hypothesis feels just like using other internal tools within the Moodle. More about Deep Linking can be read here.

Who is this guide for?

• This guide is for Moodle administrators who want to include an API token that will unlock additional features to an existing Hypothesis LMS app deployment
• If you are installing the Hypothesis LMS app in Moodle for the first time please see our full installation guide here

Enable Deep Linking

1. Open the “Site Administration” page, and in the “Search” field type “manage tools” and hit enter
2. Under Search results click the Manage tools link.
   Note: The typical path to the Manage tools page will be Administration / Plugins / Activity modules / External tool / Manage tools though some Moodle sites may be configured differently.
3. Look for the Hypothesis tool and click the gear icon or the edit button on it.
   
   
4. Perform the following steps below based on whether you are using LTI 1.1 or LTI 1.3. 

Before proceeding with the steps to set up the Hypothesis API, make sure first that Web Services and REST Protocol are both enabled in your Moodle instance. These are components that should be enabled for the API to function correctly once it has been set up. Here are the steps to check if these two items are enabled.

Web Services

1. Click Site Administration and search for Web Services.
2. On the results, look for Advanced Features. Enable Web Services will be under that category. Make sure that it is checked.

REST Protocol

1. Click Site Administration and search for REST Protocol.
2. On the results, look for Manage protocols. REST Protocol will be under that category. Make sure that the eye icon across it is not crossed out, suggesting that it is enabled.

API Setup

In this part of the setup, the Moodle admin has to pick a user where the API token will be associated. The admin can use their own user or a generic admin user account. If a new user account will be used, make sure that the new user account is not required to change password or has pending policies (privacy) that needs to be completed. Make sure to have a user that will be associated with the API token ready before proceeding further.

1. Role Creation

2. 1. Open the “Site Administration” page, and in the “Search” field type “Define Role” and hit enter.
   2. Under Search results click the Define Roles link.

Note: The typical path to the Define Roles page will be Administration / Users / Permissions / Define Roles though some Moodle sites may be configured differently.

1. 3. Click Add a New Role.
   4. Click Continue.
   5. Fill out the “Adding a New Role” page using the guide below.

• • • Short Name:
      • Hypothesis
    • Custom Full Name
      • Hypothesis
    • Role archetype
      • None
    • Context types where this role may be assigned
      • System
    • Allow role assignments
      • None
    • Allow role overrides
      • None
    • Allow role switches
      • None
    • Allow role to view
      • None
    • Capabilities
      • moodle/course:managegroups
      • moodle/course:view

1. 6. Click Create this Role.

2. External Service

3. 1. Open the “Site Administration” page, and in the “Search” field type “External Service” and hit enter.
   2. Under Search results click the External Services link.

Note: The typical path to the Define Roles page will be Administration / Server / Web Services / External Services though some Moodle sites may be configured differently.

1. 3. Click Add.
   4. Fill out the “External Service” page using the guide below.

• • • Name:
      • Hypothesis
    • Short Name
      • Hypothesis
    • Click Show more… and enable the following:
      • Enabled
      • Authorized users only
      • Can download files
    • Required Capability
      • No Required Capability

1. 5. Click Save Changes.
      
      
   6. Click Add Functions.
   7. Click the dropdown arrow and locate each function listed below. Click the function on the results list to include it as a function.

• • • core_course_get_contents
    • core_group_get_course_groupings
    • core_group_get_course_user_groups
    • core_group_get_groupings
    • mod_page_get_pages_by_courses

1. 1. 8. Click Add Functions.
      9. Go back to External Services by opening the “Site Administration ” page, and in the “Search” field type “External Service ” and hit enter. Under Search results click the External Services link.
      10. Locate the External Service that has just been created and click the Authorized Users link across it.
      11.  Select the user that will be associated with the API token that you will be creating in the next set of steps.
      12. Click Add.
          

3. API Token Creation
4. 1. Open the “Site Administration” page, and in the “Search” field type “Manage Token” and hit enter.
   2. Under Search results click the Manage Tokens link.
   3. Note that the typical path to the Define Roles page will be Administration / Server / Web Services / Manage Tokens though some Moodle sites may be configured differently.
   4. Click Create Token.
      • Fill out the “Create Token” page using the guide below.
      • Name:
        • Hypothesis
      • User
        • Select the user where this API token will be associated with
      • Service
        • Hypothesis (this is the External Service you earlier selected)
      • Uncheck the box across Valid Until

1. 5. Click Save Changes.
   6. Click Copy to Clipboard to copy your API token. Make sure to save a copy of it since you will not be able to retrieve the API token within Moodle once you leave the Manage Tokens Page.

Submit the API registration details

1. Gather the text document that you copied values into during the above steps. At this point, you must have the following registration details:
   • Moodle API Token
   • Consumer Key (For LTI 1.1)
   • Deployment ID (For LTI 1.3)
2. Open our Moodle API Token Registration form
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 URL
    • Enter the web address of your Moodle instance, e.g. https://myschool.moodlecloud.com/
  • Moodle API Token
    • Enter the Moodle API Token previously copied from above
  • Deployment ID (For LTI 1.3 only)
    • Enter the LTI Deployment ID previously copied from above
  • Consumer Key (For LTI 1.1 only)
    • Enter the Consumer Key previously copied from above
  • Additional notes (optional)
    • Include any optional additional notes for the Hypothesis support team

4. Click Submit to send your API registration info to Hypothesis.

We will email the address you provided above when your registration has been processed, and the additional Hypothesis Moodle integration features such as Moodle Files, Groups, Pages and Folders have been turned on.