Canvas API Integration

Introduction

Welcome to the HelioCampus Canvas API Integration Guide. This document provides step-by-step instructions for configuring the integration between HelioCampus Assessment & Credentialing and Canvas using API standards and completing the HelioCampus Assessment & Credentialing LMS Information Form .

Generating a Canvas API Developer Key

A Canvas API Developer Key is required to enable HelioCampus to retrieve data from Canvas for use in HelioCampus Assessment & Credentialing. A Canvas Administrator must generate an API Developer Key within the institution's Canvas instance by following these steps:

1. Navigate to Developer Key Settings

1. Log into Canvas as an Admin.

2. Navigate to Admin and select the appropriate managed account.

3. Click Developer Keys.

4. Click the + Developer Key button and choose API Key.

2. Configure the Key Settings

In the Key Settings dialog, enter the following details:

3. Save and Activate the Key

1. Click Save.

2. Verify that the key appears in the list.

3. Change the State of the key to ON.

4. Copy Developer Key Details

1. Locate the Developer Key ID and copy it.

   

2. Paste the Developer Key ID into the API Developer Key field on the HelioCampus Assessment & Credentialing LMS Information Form.

3. Click Show Key to reveal the Developer Key Secret.

4. Copy the Developer Key Secret and paste it into the API Developer Secret field on the HelioCampus Assessment & Credentialing LMS Information Form.

If you are not going to enable scopes on the API key and have completed the LTI 1.3 integration steps, you may now submit the HelioCampus Assessment and Credentialing LMS Information Form and continue to HelioCampus Canvas Service Account
Otherwise, continue to Applying scopes to HelioCampus API integration below.

Applying scopes to HelioCampus API integration

If your institution requires developer keys in Canvas LMS to enforce scopes, you must configure the necessary scopes in the developer key created during integration.

What Are Scopes?

Enforcing scopes in a Canvas API developer key restricts API calls to predefined permissions, ensuring security and preventing unauthorized access to data. If a request exceeds its allowed scope, it will be denied.

Note: Enforcing scopes requires re-authorizing the API token with HelioCampus when new scopes are added or optional scopes are enabled. This may add complexity to the process.

1. Required Scopes

Check the box under API Developer Key Scoped? on the HelioCampus Assessment and Credentialing LMS Information Form.

To apply the required scopes:

1. Toggle Enforce Scopes to ON.

2. Check Allow Include Parameters.

To enable the following scopes, locate the corresponding header in the scope list, expand it, and check the required scope.

Assignments

• GET /api/v1/courses/:course_id/assignments

Courses

• GET /api/v1/courses

• GET /api/v1/courses/:id

• GET /api/v1/courses/:course_id/users

Sections

• GET /api/v1/courses/:course_id/sections

Note: The HelioCampus Assessment & Credentialing scheduled job updateLmsCrosslistedSectionIds uses this API to determine cross-listed Canvas sections.

Enrollments

• GET /api/v1/courses/:course_id/enrollments

OAuth2

• /auth/userinfo

Submissions

• GET /api/v1/courses/:course_id/assignments/:assignment_id/submissions

• GET /api/v1/courses/:course_id/students/submissions

2. Optional Scopes

Account Reports

If your institution utilizes cross-listed courses, enable the following scopes:

If enabled, Check the box under Account Reports scopes on the HelioCampus Assessment and Credentialing LMS Information Form.

• POST /api/v1/accounts/:account_id/reports/:report

• GET /api/v1/accounts/:account_id/reports/:report/:id

• GET /api/v1/accounts/:account_id/reports

• GET /api/v1/accounts/:account_id/reports/:report

Additionally, you will have to supply the account_id found in the institution’s Canvas URL (typically 1)

Type the account_idin Account Reports Account ID on the HelioCampus Assessment and Credentialing LMS Information Form.

Note: The HelioCampus Assessment & Credentialing scheduled job updateLmsCrosslistedSectionIds relies on this API to determine cross-listed Canvas sections.

Quiz Report Scopes

If your institution assesses quiz data in HelioCampus, enable:

If enabled, Check the box under Quiz Reports scopes on the H e lioCampus Assessment and Credentialing LMS Information Form.

Quiz Reports

• GET /api/v1/courses/:course_id/quizzes/:quiz_id/reports

• GET /api/v1/courses/:course_id/quizzes/:quiz_id/reports/:id

• POST /api/v1/courses/:course_id/quizzes/:quiz_id/reports

Note: HelioCampus Assessment & Credentialing requires POST API scope to retrieve quiz grades and answers in a batch format, avoiding multiple calls per student.
Example API Call:https://<Canvas_URL>/api/v1/courses/<Course_ID>/quizzes/<Quiz_ID>/reports?quiz_report[report_type]=student_analysis&access_token=XXXX

Quiz Questions

If your institution assesses quiz data in HelioCampus, enable:

If enabled, Check the box under Quiz Questions scopes on the HelioCampus Assessment and Credentialing LMS Information Form.

• GET /api/v1/courses/:course_id/quizzes/:quiz_id/questions

• POST /api/quiz/v1/courses/:course_id/quizzes/:assignment_id/reports

• GET /api/v1/progress/:id

Files

If your institution assesses quiz data in HelioCampus, enable:

If enabled, Check the box under Files scopes on the HelioCampus Assessment and Credentialing LMS Information Form.

• GET /api/v1/files/:id

Note: This scope allows HelioCampus Assessment & Credentialing to access student submission files for quiz questions requiring file uploads.

Posting Grades to LMS

If your institution plans on posting grades back to Canvas from , enable:

If enabled, Check the box under Submissions scopes on the HelioCampus Assessment and Credentialing LMS Information Form.

Submissions

• POST /api/v1/courses/:course_id/assignments/:assignment_id/submissions/update_grades

If you have also completed the LTI 1.3 integration steps, you may now submit the HelioCampus Assessment and Credentialing LMS Information Form and continue to HelioCampus Canvas Service Account.

HelioCampus Canvas Service Account

This section outlines the steps to create a service account for REST API calls between Canvas environment and HelioCampus Assessment & Credentialing. This integration enables HelioCampus to gather necessary data for assessment purposes. The following steps must be completed by a Canvas Administrator and a HelioCampus Institutional Admin at your institution.

1. Create the Service Account in Canvas

Create an account in Canvas, the type of account (local Canvas account or university account) should follow your institution’s policies.
Ensure that the account setup follows the same format as other user accounts (e.g., if user login includes an email address and SIS ID, the service account should follow the same format).

1. Log into Canvas as an Admin.

2. Navigate to Admin and select the appropriate managed account.

3. Click People

4. Click the + People button

5. Fill out the required fields:

1. Uncheck Email the user about this account creation

2. Click Add User

If you plan on matching on SIS ID or Integration ID:

1. Find and click on the user that you just created.

2. Under Login Information, click the Edit (pencil icon).

3. Add the following values:

1. Click Update Login to save the changes.

2. Create a Service Role in Canvas

Create an Account Role that grants the service account the necessary permissions.

1. Log into Canvas as an Admin.

2. Navigate to Admin and select the appropriate managed account.

3. Click Permissions

4. Click Account Roles

5. Click Add Role

6. Role Name: HelioCampus Service Role

7. Click Save

8. Enable Required Permissions:

   • Course Content - view

   • Courses - view list

   • Grades - view all grades

   • SIS Data - read

   • Users - view login IDs

   • Users - view primary email address

9. Enable Optional Permissions:

   • Manage Assignments and Quizzes - Enable if your institution plans on assessing quiz data in HelioCampus Assessment & Credentialing.

   • Grades - edit - Enable if your institution plans on sending student grades for converted assignments in HelioCampus Assessment & Credentialing back to Canvas.

   • Reports - manage - Enable if your institution utilizes cross-listed courses.

10. Click X to close the new role.

3. Assign the Service Role to the Service Account

1. Log into Canvas as an Admin.

2. Navigate to Admin and select the appropriate managed account.

3. Click Settings

4. Click Admins

5. Scroll to the bottom and Click + Account Admins

6. Click the Add More drop-down menu, select the service role created in Step 2.

7. Enter the email address or username of the service account created in Step 1.

8. Click Continue.

9. If the user appears with a check, Click OK, Looks Good, Add This 1 User to finalize the setup.

Create the Service Account in HelioCampus Assessment & Credentialing

To integrate the service account you created in Canvas with HelioCampus Assessment & Credentialing, follow these steps.

This step should be completed by one of your institution’s HelioCampus Assessment & Credentialing Institutional Admins.

1. Log into your institution’s HelioCampus Assessment & Credentialing

2. Click the hamburger menu in the top left corner.

3. Scroll down to the Admin Tools section of the menu.

4. Click on User Accounts Manager.

5. Click + NEW USER in the top right corner.

6. Choose Local User Account.

7. Fill in the User Details with the service account information from Canvas.

1. Click + ADD ROLE

2. Click the Select a role category drop-down menu, select General.

3. Click the Select a role category drop-down menu, select Institutional Admin.

4. Click the Select one or more Institutions drop-down menu, select your institution.

5. Click ADD ROLE.

Once all steps are completed, return to the main Canvas Integration Guide to finalize the integration.