Echo360's REST API integration essentially provides Echo360 with an "LMS/VLE course lookup by Instructor" capability. This integration provides two features:
- The ability for Echo360 admins or schedulers to create both Echo360 sections and connect capture schedules directly to LMS Courses. This is described in Linking an Echo360 Capture Schedule to an LMS Course.
- The ability for instructors to see and use the consolidated Analytics tab, which provides viewing and polling response data in one place for all of their LMS-course-related Echo360 media.
The basic process for API integration is:
- Create a Developer Key in Canvas.
- Copy the ID and Secret values from Canvas to Echo360.
- Authorize the configuration.
- Test the configuration.
- Optionally: Set Scope restrictions to the Canvas Developer Key.
As with most LMS-to-Echo360 configurations, this requires that you are logged into Echo360 and the LMS as an administrator, AND that you have both programs open in separate browser windows. You will be copying and pasting values from one to the other.
Best Practices for application user access: The API integration requires a user Email address. It can be a specific person's email address or it can be an application user account you create for the this purpose. The account must have administrator rights in Canvas. This is the user that will lock down the integration if your institution wishes to do so at any point in the future. For this reason, we recommend using an application user instead of an actual user.
To configure API integration between Echo360 and Canvas
- Log into Canvas as an administrator and click Admin from the left navigation, then select the main Account level.
- From the left side of the page, select Developer Keys, identified in the below figure.
- Click the Add Developer Key button from the top right of the page, and select API Key from the options given.
- In the Key Settings page, shown below, ensure that Enforce Scopes is turned OFF. If you are using scope restrictions as discussed at the bottom of this page, those must be enabled AFTER the initial configuration and authorization.
- Enter a Key Name that clearly identifies its purpose.
- Enter your Email address, identifying who created the key.
- In the Redirect URI field enter the following, also shown in the following figure:
https://echo360.org/lms/api/oauth2/complete
NOTE: As with most tooling, replace the base domain with your region-specific Echo360 domain as necessary. - Be sure Canvas is selected as the Client Credentials Audience at the bottom of the left side of the form. It is the default setting.
- Click Save.
When the list of Developer Keys appears, your new key is listed at the top. - On the right side of the new key row, toggle the key ON in order to use it. It is OFF by default.
- If you haven't already, open a new browser tab or window for Echo360 and log in as an administrator.
- Click the Settings icon in the top right of the main menu, then select Configurations, as shown in the below figure. The LMS Configurations tab is shown by default.
- In the main panel of the page, click the APIs tab, as identified in the above figure.
- Click Add Configuration.
- In the form that appears, shown below, enter a Name for the configuration.
- Enter the your Canvas Domain (base URL of your Canvas instance).
- Return to the Canvas window with the Developer Keys list still showing, and select and copy (ctrl+c/cmd+c) the number shown in the Details column for the key you just created, as identified in the below figure.
- Return to Echo360 and paste the value (ctrl+v/cmd+v) into the LMS API Client ID field of the API Configuration modal.
- Return to Canvas and click Show Key to expose the Key secret, then select and copy the secret.
- Return to Echo360 and paste the key secret value into the LMS API Client Secret field of the API Configuration modal.
- Click Save.
- In the API tab that appears with your new configuration, click Authorize as shown in the below figure.
- In the popup that appears, you may need to log into Canvas as an administrator unless you are already logged in through this browser.
- When prompted, click Authorize in the Canvas window, to allow the key to access your Canvas account.
After authorization, the popup closes and the API tab appears again. - Click Test to ensure the configuration and communication works properly.
- In the popup appears, enter an email address for a Canvas instructor known to have courses, then click Search.
NOTE: If the instructor is enrolled into a Canvas course via the UI, the instructor must actively Accept the invitation to the course before the course will appear in the search results. If using an SIS or other integration tool, the "accept" step is not necessary. See the Canvas Community Forum for more information if needed.
If the configuration is successful, the bottom section of the test modal is populated with a list of that instructor's Canvas courses, as shown in the below figure. You can close the dialog box using the X in the top right corner.
You are done! You can now Link your Echo360 capture schedules to LMS courses. And your instructors will now see an Analytics tab in their main menu navigation, to access to their LMS-course related media data.
Required Scopes for Echo360 API Integration
If you need to enforce scopes for your API keys, as many do, you must be sure to enable the scopes listed below in the Key Settings for the Developer Key you created for Echo360.
BE ADVISED that this list will change as we expand the use of the API integration. Future features may require enabling additional scopes.
- Under Courses, enable
url:GET|/api/v1/users/:user_id/courses
- Under Users, enable
url:GET|/api/v1/accounts/:account_id/users
- Under Enrollments, enable
url:GET|/api/v1/courses/:course_id/enrollments
YOU MUST be sure to configure the initial API setup WITHOUT scopes enforced. Then Authorize and Test the configuration with Echo360 as the above procedure states. After you have confirmed communication between the two systems, you can then enable Enforce Scopes, select the required scopes, and Save.
Once you have enabled the appropriate scopes, RETEST the integration using the last few steps above, to be sure that the integration is still working as expected. If you have problems or questions, please contact your customer success representative, or email support@echo360.com.