> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Canvas Scopes Reference

> Complete reference of Canvas API scopes for the call_canvas and search_canvas tools — anatomy, common scopes by category, starter configurations, and troubleshooting.

This is the full scope reference for the [Pria Canvas tools](/mdx/integrations/canvas/pria-tools). Use it to discover which Canvas REST API endpoints your Digital Twin needs, then configure them on both the Canvas Developer Key and your Digital Twin instance.

## Canvas Scopes

### Understanding Scopes

Canvas API scopes are permission controls that act as a **whitelist** for your application's API access. When scope enforcement is enabled on a Developer Key, Canvas will only allow API calls to endpoints that have been explicitly authorized — all other requests are rejected with a 401 error, regardless of the user's Canvas role.

Scopes must be configured in **two places**:

1. **Canvas Developer Key** — controls what Canvas will allow at the API level
2. **Digital Twin Instance Configuration** — controls what your Digital Twin is permitted to request

Both lists must match. If a scope is missing from either location, the corresponding API call will fail.

**Key Concepts**:

* **Whitelist Model**: Only explicitly enabled scopes are allowed — everything else is blocked
* **Endpoint-Specific**: Each scope maps to a specific API endpoint and HTTP method (e.g., GET, POST, PUT, DELETE)
* **Dual Configuration**: Scopes must be enabled on the Canvas Developer Key *and* listed in your Digital Twin instance
* **Principle of Least Privilege**: Grant only the scopes your Digital Twin actually needs

<Warning>
  Only grant scopes your Digital Twin actually uses. Over-permissioning creates unnecessary security risk. Use the [recommended development workflow](#best-practices-for-scope-management) to discover exactly which scopes you need before enabling enforcement.
</Warning>

### Scope Anatomy

Each scope is a pipe-delimited string with three components:

```
url:<HTTP_METHOD>|<API_ENDPOINT>
```

**Components**:

1. **Literal prefix**: Always starts with `url:`
2. **HTTP Method**: `GET`, `POST`, `PUT`, or `DELETE`
3. **Endpoint Path**: The API path without the domain

**Example Scope**:

```
url:GET|/api/v1/courses/:course_id/enrollments
```

This scope allows:

* **Method**: GET (read-only)
* **Resource**: Course enrollments
* **Context**: Within a specific course

<Note>
  **Path Variables**: URL parameters are written with colon notation (e.g., `:user_id`, `:course_id`, `:assignment_id`). When defining scopes, ensure variable names match exactly—scope comparison is token-based and case-sensitive.
</Note>

### Official Documentation

For the complete, authoritative list of all available Canvas API scopes and endpoints, consult:

[Canvas REST API Documentation](https://developerdocs.instructure.com/services/canvas)

### Common Scopes by Category

<AccordionGroup>
  <Accordion title="Assignments" icon="clipboard-list">
    **List Assignments**:

    ```
    Endpoint: /api/v1/courses/:course_id/assignments
    Scope: url:GET|/api/v1/courses/:course_id/assignments
    ```

    **Get Single Assignment**:

    ```
    Endpoint: /api/v1/courses/:course_id/assignments/:id
    Scope: url:GET|/api/v1/courses/:course_id/assignments/:id
    ```

    **Update Submission** (grading, comments):

    ```
    Endpoint: /api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id
    Scope: url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id
    ```

    **List Submissions**:

    ```
    Endpoint: /api/v1/courses/:course_id/assignments/:assignment_id/submissions
    Scope: url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions
    ```
  </Accordion>

  <Accordion title="Discussions" icon="comments">
    **List Discussion Topics**:

    ```
    Endpoint: /api/v1/courses/:course_id/discussion_topics
    Scope: url:GET|/api/v1/courses/:course_id/discussion_topics
    ```

    **Create Discussion**:

    ```
    Endpoint: /api/v1/courses/:course_id/discussion_topics
    Scope: url:POST|/api/v1/courses/:course_id/discussion_topics
    ```

    **Get Discussion Entries**:

    ```
    Endpoint: /api/v1/courses/:course_id/discussion_topics/:topic_id/entries
    Scope: url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries
    ```
  </Accordion>

  <Accordion title="Grades & Submissions" icon="chart-line">
    **List All Submissions**:

    ```
    Endpoint: /api/v1/courses/:course_id/submissions
    Scope: url:GET|/api/v1/courses/:course_id/submissions
    ```

    **Get User Grades**:

    ```
    Endpoint: /api/v1/courses/:course_id/students/submissions
    Scope: url:GET|/api/v1/courses/:course_id/students/submissions
    ```
  </Accordion>

  <Accordion title="Quizzes" icon="circle-question">
    **List Quizzes**:

    ```
    Endpoint: /api/v1/courses/:course_id/quizzes
    Scope: url:GET|/api/v1/courses/:course_id/quizzes
    ```

    **Get Quiz Submissions**:

    ```
    Endpoint: /api/v1/courses/:course_id/quizzes/:quiz_id/submissions
    Scope: url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions
    ```
  </Accordion>

  <Accordion title="Announcements" icon="bullhorn">
    **List Announcements**:

    ```
    Endpoint: /api/v1/courses/:course_id/announcements
    Scope: url:GET|/api/v1/courses/:course_id/announcements
    ```

    **Create Announcement**:

    ```
    Endpoint: /api/v1/courses/:course_id/discussion_topics
    Scope: url:POST|/api/v1/courses/:course_id/discussion_topics
    ```

    (Announcements are special discussion topics)
  </Accordion>

  <Accordion title="Modules & Content" icon="book">
    **List Modules**:

    ```
    Endpoint: /api/v1/courses/:course_id/modules
    Scope: url:GET|/api/v1/courses/:course_id/modules
    ```

    **List Module Items**:

    ```
    Endpoint: /api/v1/courses/:course_id/modules/:module_id/items
    Scope: url:GET|/api/v1/courses/:course_id/modules/:module_id/items
    ```

    **List Pages**:

    ```
    Endpoint: /api/v1/courses/:course_id/pages
    Scope: url:GET|/api/v1/courses/:course_id/pages
    ```

    **Get Page Content**:

    ```
    Endpoint: /api/v1/courses/:course_id/pages/:url_or_id
    Scope: url:GET|/api/v1/courses/:course_id/pages/:url_or_id
    ```
  </Accordion>

  <Accordion title="Users & Enrollments" icon="users">
    **List Course Users**:

    ```
    Endpoint: /api/v1/courses/:course_id/users
    Scope: url:GET|/api/v1/courses/:course_id/users
    ```

    **List Enrollments**:

    ```
    Endpoint: /api/v1/courses/:course_id/enrollments
    Scope: url:GET|/api/v1/courses/:course_id/enrollments
    ```
  </Accordion>

  <Accordion title="Files & Documents" icon="file">
    **List Course Files**:

    ```
    Endpoint: /api/v1/courses/:course_id/files
    Scope: url:GET|/api/v1/courses/:course_id/files
    ```

    **Get File Details**:

    ```
    Endpoint: /api/v1/courses/:course_id/files/:id
    Scope: url:GET|/api/v1/courses/:course_id/files/:id
    ```
  </Accordion>

  <Accordion title="Groups" icon="user-group">
    **List Course Groups**:

    ```
    Endpoint: /api/v1/courses/:course_id/groups
    Scope: url:GET|/api/v1/courses/:course_id/groups
    ```
  </Accordion>

  <Accordion title="Rubrics" icon="table">
    **List Rubrics**:

    ```
    Endpoint: /api/v1/courses/:course_id/rubrics
    Scope: url:GET|/api/v1/courses/:course_id/rubrics
    ```
  </Accordion>

  <Accordion title="Assignment Groups" icon="folder">
    **List Assignment Groups**:

    ```
    Endpoint: /api/v1/courses/:course_id/assignment_groups
    Scope: url:GET|/api/v1/courses/:course_id/assignment_groups
    ```
  </Accordion>

  <Accordion title="Analytics" icon="chart-bar">
    **Course Activity**:

    ```
    Endpoint: /api/v1/courses/:course_id/analytics/activity
    Scope: url:GET|/api/v1/courses/:course_id/analytics/activity
    ```

    **Assignment Analytics**:

    ```
    Endpoint: /api/v1/courses/:course_id/analytics/assignments
    Scope: url:GET|/api/v1/courses/:course_id/analytics/assignments
    ```

    **Student Summaries**:

    ```
    Endpoint: /api/v1/courses/:course_id/analytics/student_summaries
    Scope: url:GET|/api/v1/courses/:course_id/analytics/student_summaries
    ```

    **Individual Student Activity**:

    ```
    Endpoint: /api/v1/courses/:course_id/analytics/users/:student_id/activity
    Scope: url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity
    ```
  </Accordion>

  <Accordion title="Smart Search" icon="magnifying-glass">
    **Smart Search** (recommended fallback):

    ```
    Endpoint: /api/v1/courses/:course_id/smartsearch
    Scope: url:GET|/api/v1/courses/:course_id/smartsearch
    ```
  </Accordion>

  <Accordion title="Calendar" icon="calendar">
    **User Calendar Events**:

    ```
    Endpoint: /api/v1/users/:user_id/calendar_events
    Scope: url:GET|/api/v1/users/:user_id/calendar_events
    ```
  </Accordion>
</AccordionGroup>

### Choosing Scopes for Your Use Case

Select scopes based on the specific functionality your Digital Twin needs to provide:

**Example: Auto-Grader Assistant**

```
url:GET|/api/v1/courses/:course_id/assignments
url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions
url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id
```

**Example: Student Support Bot**

```
url:GET|/api/v1/courses/:course_id/assignments
url:GET|/api/v1/courses/:course_id/discussion_topics
url:GET|/api/v1/courses/:course_id/pages
url:GET|/api/v1/users/:user_id/calendar_events
```

**Example: Course Analytics Dashboard**

```
url:GET|/api/v1/courses/:course_id/analytics/activity
url:GET|/api/v1/courses/:course_id/analytics/assignments
url:GET|/api/v1/courses/:course_id/analytics/student_summaries
url:GET|/api/v1/courses/:course_id/submissions
```

### Best Practices for Scope Management

<Tip>
  **Recommended Development Workflow**:

  1. **Development Phase**: Disable scope enforcement to allow unrestricted API exploration
  2. **Documentation Phase**: Monitor Tool Details in dialog history to identify all endpoints used
  3. **Compilation Phase**: Create a comprehensive list of required scopes in a JSON file
  4. **Testing Phase**: Enable scope enforcement and test all functionality
  5. **Production Phase**: Deploy with minimal, verified scopes

  This approach ensures you grant exactly the permissions needed—no more, no less.
</Tip>

### Starter Scope Configuration

Use this starter JSON as a foundation for your scope configuration. This includes commonly used endpoints for typical Digital Twin functionality:

```json theme={null}
[
  "url:GET|/api/v1/courses/:course_id/analytics/activity",
  "url:GET|/api/v1/courses/:course_id/analytics/assignments",
  "url:GET|/api/v1/courses/:course_id/analytics/student_summaries",
  "url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity",
  "url:GET|/api/v1/courses/:course_id/announcements",
  "url:GET|/api/v1/courses/:course_id/assignments",
  "url:GET|/api/v1/courses/:course_id/assignments/:id",
  "url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions",
  "url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id",
  "url:GET|/api/v1/courses/:course_id/assignment_groups",
  "url:GET|/api/v1/courses/:course_id/discussion_topics",
  "url:GET|/api/v1/courses/:course_id/enrollments",
  "url:GET|/api/v1/courses/:course_id/files",
  "url:GET|/api/v1/courses/:course_id/files/:id",
  "url:GET|/api/v1/courses/:course_id/groups",
  "url:GET|/api/v1/courses/:course_id/modules",
  "url:GET|/api/v1/courses/:course_id/modules/:module_id/items",
  "url:GET|/api/v1/courses/:course_id/pages",
  "url:GET|/api/v1/courses/:course_id/pages/:url_or_id",
  "url:GET|/api/v1/courses/:course_id/quizzes",
  "url:GET|/api/v1/courses/:course_id/smartsearch",
  "url:GET|/api/v1/courses/:course_id/submissions",
  "url:GET|/api/v1/courses/:course_id/users",
  "url:GET|/api/v1/users/:user_id/calendar_events"
]
```

### Suggested Scopes

Here is a [list of scopes suggested by Pria](https://gitlab.com/praxis-ai/pria-client-sdk/-/blob/c5f3fb53553d1a1ee1b6ddc79685475e35cf0b5c/canvas/canvas-scope-pria-suggestion.md),

Here's the enhanced list with the most common Canvas API operations for students and teachers:

```javascript theme={null}
[
  // Analytics (Teachers)
  "url:GET|/api/v1/courses/:course_id/analytics/activity",
  "url:GET|/api/v1/courses/:course_id/analytics/assignments",
  "url:GET|/api/v1/courses/:course_id/analytics/student_summaries",
  "url:GET|/api/v1/courses/:course_id/analytics/users/:student_id/activity",
  
  // Announcements
  "url:GET|/api/v1/courses/:course_id/announcements",
  "url:POST|/api/v1/courses/:course_id/discussion_topics", // Create announcement
  "url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id", // Update announcement
  "url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id", // Delete announcement
  
  // Assignments
  "url:GET|/api/v1/courses/:course_id/assignments",
  "url:GET|/api/v1/courses/:course_id/assignments/:id",
  "url:POST|/api/v1/courses/:course_id/assignments", // Create assignment (Teachers)
  "url:PUT|/api/v1/courses/:course_id/assignments/:id", // Update assignment (Teachers)
  "url:DELETE|/api/v1/courses/:course_id/assignments/:id", // Delete assignment (Teachers)
  "url:GET|/api/v1/courses/:course_id/assignment_groups",
  "url:POST|/api/v1/courses/:course_id/assignment_groups", // Create assignment group (Teachers)
  "url:PUT|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id", // Update group (Teachers)
  
  // Submissions
  "url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions",
  "url:GET|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id", // View single submission
  "url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/submissions", // Submit assignment (Students)
  "url:PUT|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id", // Grade/update submission
  "url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id/comments", // Add comment
  "url:GET|/api/v1/courses/:course_id/students/submissions", // Get user's own submissions (Students)
  "url:GET|/api/v1/courses/:course_id/submissions", // All submissions (Teachers)
  "url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/update_grades", // Bulk grade (Teachers)
  
  // Discussion Topics & Entries
  "url:GET|/api/v1/courses/:course_id/discussion_topics",
  "url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id",
  "url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries", // View discussion posts
  "url:POST|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries", // Post to discussion
  "url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id", // Edit post
  "url:DELETE|/api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id", // Delete post
  "url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id/view", // Mark as read
  
  // Enrollments
  "url:GET|/api/v1/courses/:course_id/enrollments",
  "url:POST|/api/v1/courses/:course_id/enrollments", // Enroll users (Teachers)
  "url:DELETE|/api/v1/courses/:course_id/enrollments/:id", // Remove enrollment (Teachers)
  
  // Files & Folders
  "url:GET|/api/v1/courses/:course_id/files",
  "url:GET|/api/v1/courses/:course_id/files/:id",
  "url:POST|/api/v1/courses/:course_id/files", // Upload file
  "url:DELETE|/api/v1/files/:id", // Delete file
  "url:GET|/api/v1/courses/:course_id/folders",
  "url:GET|/api/v1/folders/:id",
  "url:POST|/api/v1/courses/:course_id/folders", // Create folder
  
  // Grades & Gradebook
  "url:GET|/api/v1/courses/:course_id/gradebook_history/feed",
  "url:GET|/api/v1/courses/:course_id/assignment_groups/:assignment_group_id/grades",
  "url:POST|/api/v1/courses/:course_id/assignments/:assignment_id/submissions/:user_id", // Post grade
  
  // Groups
  "url:GET|/api/v1/courses/:course_id/groups",
  "url:GET|/api/v1/groups/:group_id",
  "url:GET|/api/v1/groups/:group_id/users",
  "url:POST|/api/v1/courses/:course_id/groups", // Create group (Teachers)
  
  // Modules
  "url:GET|/api/v1/courses/:course_id/modules",
  "url:GET|/api/v1/courses/:course_id/modules/:module_id",
  "url:GET|/api/v1/courses/:course_id/modules/:module_id/items",
  "url:GET|/api/v1/courses/:course_id/modules/:module_id/items/:id",
  "url:POST|/api/v1/courses/:course_id/modules", // Create module (Teachers)
  "url:PUT|/api/v1/courses/:course_id/modules/:module_id", // Update module (Teachers)
  "url:POST|/api/v1/courses/:course_id/modules/:module_id/items", // Add module item (Teachers)
  "url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id/done", // Mark item complete (Students)
  
  // Pages
  "url:GET|/api/v1/courses/:course_id/pages",
  "url:GET|/api/v1/courses/:course_id/pages/:url_or_id",
  "url:POST|/api/v1/courses/:course_id/pages", // Create page (Teachers)
  "url:PUT|/api/v1/courses/:course_id/pages/:url_or_id", // Update page (Teachers)
  "url:DELETE|/api/v1/courses/:course_id/pages/:url_or_id", // Delete page (Teachers)
  "url:GET|/api/v1/courses/:course_id/front_page", // Get front page
  
  // Quizzes
  "url:GET|/api/v1/courses/:course_id/quizzes",
  "url:GET|/api/v1/courses/:course_id/quizzes/:id",
  "url:POST|/api/v1/courses/:course_id/quizzes", // Create quiz (Teachers)
  "url:PUT|/api/v1/courses/:course_id/quizzes/:id", // Update quiz (Teachers)
  "url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions", // Quiz submissions
  "url:POST|/api/v1/courses/:course_id/quizzes/:quiz_id/submissions", // Start quiz (Students)
  "url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/questions", // Get quiz questions
  
  // Rubrics
  "url:GET|/api/v1/courses/:course_id/rubrics",
  "url:GET|/api/v1/courses/:course_id/rubrics/:id",
  "url:POST|/api/v1/courses/:course_id/rubrics", // Create rubric (Teachers)
  
  // Users & Profiles
  "url:GET|/api/v1/courses/:course_id/users",
  "url:GET|/api/v1/users/:id",
  "url:GET|/api/v1/users/:user_id/profile", // View profile
  "url:PUT|/api/v1/users/:id", // Update user settings
  "url:GET|/api/v1/users/self", // Get current user
  
  // Calendar & Events
  "url:GET|/api/v1/users/:user_id/calendar_events",
  "url:GET|/api/v1/calendar_events",
  "url:POST|/api/v1/calendar_events", // Create calendar event
  "url:PUT|/api/v1/calendar_events/:id", // Update calendar event
  
  // Courses
  "url:GET|/api/v1/courses",
  "url:GET|/api/v1/courses/:id",
  "url:PUT|/api/v1/courses/:id", // Update course (Teachers)
  "url:GET|/api/v1/courses/:course_id/settings", // Course settings
  
  // Conversations/Messages
  "url:GET|/api/v1/conversations",
  "url:POST|/api/v1/conversations", // Send message
  "url:GET|/api/v1/conversations/:id",
  "url:PUT|/api/v1/conversations/:id", // Update conversation (mark as read)
  "url:POST|/api/v1/conversations/:id/add_message", // Reply to conversation
  
  // External Tools (LTI)
  "url:GET|/api/v1/courses/:course_id/external_tools",
  "url:GET|/api/v1/courses/:course_id/external_tools/:external_tool_id",
  
  // Search & Navigation
  "url:GET|/api/v1/courses/:course_id/smartsearch",
  "url:GET|/api/v1/courses/:course_id/tabs",
  "url:GET|/api/v1/search/recipients", // Search for users to message
  
  // Additional Common Operations
  "url:GET|/api/v1/courses/:course_id/activity_stream",
  "url:GET|/api/v1/courses/:course_id/todo",
  "url:GET|/api/v1/users/:user_id/courses", // Get user's courses
  "url:GET|/api/v1/courses/:course_id/recent_students", // Recently accessed students (Teachers)
]
```

## Key Additions by User Type:

**Students:**

* POST submissions (submit assignments)
* POST discussion entries (participate in discussions)
* GET own submissions
* Mark module items as complete
* Take quizzes
* Send messages
* View their own profile

**Teachers:**

* Create/update/delete assignments, pages, modules
* Grade submissions and add comments
* Bulk grading operations
* Create announcements and discussions
* Manage enrollments and groups
* Create quizzes and rubrics
* Access analytics
* Update course settings
* Manage course files and folders

This comprehensive list covers \~95% of typical Canvas LMS interactions for both students and instructors.

<Info>
  **Latest Version**: The most current version of this starter configuration is maintained in the Praxis AI Community Repository - please contribute:

  [Canvas Scopes Configuration](https://gitlab.com/praxis-ai/pria-client-sdk/-/blob/c684acc6895695a0d1acdac3a2079d9bd14322f0/canvas/digital-twin-canvas-scopes.json)
</Info>

### Scope Troubleshooting

**Insufficient Scopes Error**:

```
Access to Canvas LMS API function at https://institution.instructure.com/api/v1/courses/53493/assignments 
is Unauthorized (401). 
{"errors":[{"message":"Insufficient scopes on access token."}],"error_report_id":"1288266"}
```

**Resolution Steps**:

1. Identify the missing scope from the error message endpoint
2. Add the scope to your Canvas Developer Key
3. Ensure the scope is also listed in your Digital Twin configuration
4. Have users re-authorize to receive updated tokens

<Warning>
  **Critical Scope Requirement**: When scopes are enforced, they must be defined in **both** locations:

  1. **Canvas Developer Key** (authorizes the application to use these scopes)
  2. **Digital Twin Configuration** (declares which scopes to request during OAuth)

  Modifying scopes requires generating new access tokens, as scope permissions are embedded in the token at creation time and cannot be changed retroactively.
</Warning>

## Related

* [Pria Canvas Tools](/mdx/integrations/canvas/pria-tools) — overview, setup, and testing for `call_canvas` and `search_canvas`
* [Digital Twin Configuration](/mdx/integrations/canvas/pria-tools#digital-twin-configuration) — where to add these scopes in your instance
* [Canvas Configuration (Admin)](/mdx/admin-guide/configuration) — instance-level Canvas settings