Pria Tools - praxis-ai

Your Digital Twin contains the call_canvas and search_canvas tools specialized in interacting with and retrieving data from Canvas using the Canvas REST APIs.

Understanding the two Canvas tools:

call_canvas — The comprehensive Canvas integration tool that provides full access to the Canvas REST API ecosystem. Use this tool for complete CRUD operations including creating assignments, grading submissions, managing enrollments, posting discussions, retrieving detailed analytics, and any operation that requires write access or complex data manipulation.
search_canvas — A lightweight, read-only tool that exclusively leverages the Canvas Smart Search API. Use this tool when you only need to discover and retrieve links to specific content within a course (such as finding a particular assignment, page, or resource). It’s optimized for quick content discovery without the overhead of full API access.

When to use each:

Choose search_canvas for simple queries like “find the syllabus” or “locate the midterm assignment”
Choose call_canvas for actions like grading, creating content, viewing detailed submission data, or any operation beyond basic search

Overview

The Pria tools for Canvas (a.k.a Canvas Tools) enables seamless, conversational access to your Canvas Learning Management System through natural language queries. Instead of navigating through multiple web pages and menus, users can simply ask questions and receive immediate, accurate responses powered by Canvas REST APIs.

Benefits and Use Cases

For Students

The Canvas tools transforms how students interact with their coursework by providing instant access to critical information:

Quick Assignment Lookups: Ask “When is my biology assignment due?” or “What assignments do I have this week?” to get immediate answers
Grade Tracking: Query “What’s my current grade in calculus?” or “Show me my quiz scores” without navigating through multiple pages
Discussion Management: Find out “What discussions do I need to respond to this week?” to stay on top of participation requirements
Deadline Management: Eliminate the stress of clicking through Canvas menus during busy study periods

For Educators

Teachers and instructors gain powerful administrative and pedagogical capabilities:

Student Progress Monitoring: Instantly identify “Which students haven’t submitted their midterm papers?” or “Show me all students who scored below 70% on the last three quizzes”
Data-Driven Instruction: Access participation data, engagement metrics, and performance analytics for early intervention strategies
Administrative Efficiency: Check enrollment numbers, retrieve discussion participation data, and manage course logistics through simple conversations
Content Management: Create discussion posts, manage assignments, and update course materials using natural language commands

Advanced Capabilities

The tools handle sophisticated queries that would typically require multiple manual steps:

Complex filtering and sorting of student data
Bulk operations on assignments and enrollments
Cross-referencing multiple data sources (grades, submissions, participation)
Automated reporting and analytics generation

How It Works

Architecture

Behind the scenes, the Canvas tools operate through a sophisticated translation layer:

Natural Language Processing: Converts user questions into structured API requests
Authentication Handling: Automatically manages OAuth tokens and session credentials
API Translation: Maps conversational queries to precise Canvas REST API endpoints
Data Formatting: Transforms API responses into human-readable, contextual answers
Error Handling: Gracefully manages API limitations and provides helpful feedback

Example Workflows

Student Query Flow:

User asks: "What discussions do I need to respond to this week?"
↓
Tool queries Canvas discussion topics API
↓
Filters results by due dates and user participation
↓
Returns formatted list of pending discussions

Instructor Query Flow:

User asks: "Create a discussion post about photosynthesis due next Friday"
↓
Tool constructs discussion topic payload
↓
Posts to Canvas discussion API with specified due date
↓
Confirms creation and provides discussion link

Administrative Query Flow:

User asks: "Which students in my AP History class have missing assignments?"
↓
Tool retrieves enrollment data and submission records
↓
Cross-references to identify gaps
↓
Returns actionable list with student details

Role-Based Access Control

The Canvas tools implement intelligent, automatic role-based access control that adapts to each user’s Canvas permissions:

Automatic Role Detection

The system determines user roles through:

SSO (Single Sign-On) authentication data
OAuth token permissions and scopes
Canvas enrollment and membership information

Permission Levels

Students

Read-Only Access

View assignments and submissions
Check grades and feedback
Access course content
Participate in discussions

Instructors

Teaching Functions

Grade assignments
Manage course content
Create discussions and assignments
View student analytics
Post announcements

Administrators

Full Access

Account management
User enrollment operations
System-wide analytics
Course creation and deletion
Institution-level settings

Security Model

The tools operate conservatively by default, restricting access to only those operations explicitly permitted by the user’s Canvas role. This ensures compliance with institutional policies and prevents unauthorized access to sensitive data.

Key Security Features:

Automatic permission verification before each API call
Scope-based access control aligned with Canvas permissions
Session-based authentication with automatic token refresh
Audit logging of all API interactions
Graceful denial of unauthorized requests with clear messaging

Getting Started

Prerequisites

Before configuring the Canvas tools, ensure you have:

Administrative access to your Canvas instance
Permissions to create Developer Keys in Canvas
Access to your Praxis Digital Twin configuration panel

Setup Overview

Create Developer Key

Generate API credentials in Canvas to enable communication between Praxis and Canvas

Disable Scope Enforcement (Development)

During initial setup, disable scope enforcement on your Developer Key so you can explore the full Canvas API without restrictions

Configure Digital Twin

Add Canvas credentials to your Praxis instance

Test & Document Scopes

Test your Digital Twin with Canvas. As you interact, note which API endpoints are used in the Agent Details of your dialog history—these are the scopes you will need

Enable Scopes (Production)

Once you have a complete list, enable scope enforcement on your Canvas Developer Key and add the same scopes to your Digital Twin instance configuration

The Developer Key you create for API access is separate and distinct from any LTI (Learning Tools Interoperability) keys used for embedding Pria as an LTI activity within Canvas.

Multi-Instance Management

For Accounts Managing Multiple Digital Twins: Organizations with multiple Digital Twin instances can streamline configuration by storing Canvas API credentials at the account level:

Centralized Configuration: Set Canvas Client ID and Secret once at the parent account level
Automatic Inheritance: All child Digital Twin instances automatically inherit these credentials
Simplified Maintenance: Update credentials in one place to affect all instances
Focus on Customization: Teachers can concentrate on behavior and content personalization rather than technical setup

Contact our support team to configure account-level Canvas credentials. This is recommended once your API scopes and configuration attributes have stabilized in your development environment.

Create Developer Keys

Developer Keys provide the authentication credentials necessary for your Digital Twin to communicate with Canvas through REST APIs.

Only one Developer Key is needed per institution and can be shared across multiple Praxis instances.

Step-by-Step Configuration

Navigate to Admin Panel

Click Admin in the left navigation menu, then select your institution’s account (e.g., “Praxis AI”).

Access Developer Keys

In the account settings, select Developer Keys from the navigation menu.

Create New API Key

a. Click the + Developer Key button in the top-right corner

b. Select + API Key from the dropdown menu

Configure Key Settings

Fill in the following required fields:

Field	Value	Purpose
Key Name	`Pria Smart Search`	Displayed in OAuth consent form
Owner Email	Your institution’s admin email	Contact for key management
Redirect URI	`https://pria.praxislxp.com/api/auth/token_complete`	OAuth callback endpoint
Icon URL	`https://pria.praxislxp.com/logo192.png`	Displayed in consent form

Leave all other fields empty.

Configure API Scopes

Scopes control which Canvas API endpoints your Developer Key is allowed to call. Think of them as a whitelist — if a scope isn’t enabled here, the API will reject the request even if the user has Canvas permissions for it.

Important: When first creating your Developer Key, we strongly recommend you disable scope enforcement. This allows unrestricted API access during development so you can discover which endpoints your Digital Twin actually needs. You will enable specific scopes later once you have a complete list.

a. Development Mode (Recommended First Step): Leave scope enforcement disabled. Interact with your Digital Twin normally and monitor the Agent Details in your dialog history — it shows exactly which Canvas API endpoints each query uses. Keep a record of these endpoints; you will need to enable them as scopes here and add them to your Digital Twin instance configuration.

b. Production Mode: Once you have documented all required endpoints, return to this Developer Key and enable scope enforcement:

Use the search box to find specific API functions (e.g., type “smart” to locate Smart Search)
Check the boxes for each API function you documented during development

Every scope you enable on this Developer Key must also be listed in your Digital Twin’s instance configuration. See the Canvas Scopes Reference for the full list of available scopes and the Digital Twin Configuration section for where to add them.

c. Click Save in the bottom-right cornerd. Enable the Developer Key by toggling the State button to “ON”

Copy Credentials

Under the Details section:

Copy the Client ID (the numeric identifier, e.g., XXX217)
Click Show Key and copy the Client Secret

Store these credentials securely—you’ll need them for Digital Twin configuration.

Remember: One Developer Key can serve multiple Praxis instances. You’ll use these credentials when configuring each Digital Twin that needs Canvas access.

Understanding Scope Enforcement

When you enable scopes for Pria’s API integration, you establish precise security boundaries:

Explicit Permissions: Define exactly which Canvas operations Pria can perform on behalf of users
Principle of Least Privilege: Grant only the minimum access necessary for required functionality
Data Protection: Ensure Pria accesses only the data it needs to function
Audit Trail: Track which API functions are authorized and used

Pria’s Canvas tools automatically implement role-based access control that respects Canvas’s native permission system. Even with broad API scopes enabled, individual users can only perform actions appropriate to their Canvas role (student, instructor, administrator).

Digital Twin Configuration

After creating your Developer Key in Canvas, you need to configure your Digital Twin instance with the API credentials.

Configuration Steps

Access Admin Panel

Click the Admin (⌂) icon at the top of your Praxis interface and select Instances

Locate Your Instance

Find your Digital Twin instance in the list and click the green Edit pencil icon on the left.

Add API Credentials

In the Edit Instance panel:a. Scroll down to the Configuration and Integration sectionb. Locate the Canvas Client ID and Canvas Client Secret fields in the Canvas sectionc. Paste the credentials you copied from the Canvas Developer Key in the Client ID and secret fields

To post comments or perform teacher-level operations, create a personal access token for a registered course instructor and enter it in the Faculty Access Token field.

API Scopes

This is where you register the scopes your Digital Twin is allowed to use. The scopes listed here must match the scopes enabled on your Canvas Developer Key — if a scope is enabled in Canvas but not listed here (or vice versa), API calls for that endpoint will fail.

If you disabled scope enforcement on your Canvas Developer Key during development (as recommended), you still need to add scopes here. This list tells your Digital Twin which Canvas API endpoints it is permitted to call.

Each scope follows the syntax url:<HTTP Verb>|<Canvas API Endpoint Path>. For example:

The scope for GET /api/v1/courses/:course_id/smartsearch is url:GET|/api/v1/courses/:course_id/smartsearch
The scope for GET /api/v1/courses/:course_id/rubrics is url:GET|/api/v1/courses/:course_id/rubrics

Add the scopes you documented during your development/testing phase. See the Canvas Scopes Reference for a complete reference of available scopes.

If no scopes are configured for the instance (or at the account level, which takes precedence), Pria requests only the Smart Search scope (url:GET|/api/v1/courses/:course_id/smartsearch) by default.

Each Canvas API endpoint has an associated scope, and Canvas Developer Key scopes can only be enabled or disabled by a root account administrator or an Instructure employee. More info: Canvas REST APIs Scopes

Use the Upload/Download buttons to manage the list with ease.

Authenticate on SDK Login

Enable the Authenticate with Canvas on SDK login toggle to require students to authenticate in Canvas and generate an authorization token before accessing the digital twin, adding an extra security layer to your integration.

Authorized Public URLs

The Canvas tools use the first URL in the public URLs list that contains .instructure.com or .edu to authenticate and execute requests against your institution’s Canvas REST APIs—ensure this URL is correct.

As an example, the first URL in the list is Praxis AI’s Instructure URL: https://praxis-ai.instructure.com.

If your institution has a vanity URL, use that instead (e.g., https://my.university.edu).

Save Configuration

Click Update at the bottom of the panel to save your changes.

These credentials enable your Digital Twin to authenticate with Canvas on behalf of users. The actual user permissions are determined by their Canvas role and the OAuth authorization they grant.

Testing Your Canvas Integration

Once configuration is complete, verify that your Digital Twin can successfully connect to Canvas. This is the authorization screen students and instructors will see when first connecting to Canvas:

Initial Connection Test

Ask a Canvas Question

Navigate to your Digital Twin and ask a Canvas-related question:

What is my course syllabus in Canvas?

Show me my upcoming assignments

Authorize Access

On first connection (or when your token expires), you’ll be prompted to authorize your Digital Twin to access Canvas:

Click the authorization link provided
Review the permissions requested
Click Authorize in the Canvas OAuth consent screen
You’ll be redirected back to Praxis automatically

Verify Response

Your Digital Twin should return relevant information from your Canvas course, confirming successful integration.

Tool Details

A comprehensive audit log of the Digital Twin’s Canvas interactions via the call_canvas tool is available in the Tool Details section of each response, allowing you to review successful execution status and identify the specific API functions that were called during the interaction.

Token Management: Access tokens are valid for 60 minutes and are automatically refreshed in the background to maintain seamless access. You typically only need to authorize once per session or when tokens expire.

What to Test

Verify different types of queries based on your role: Students:

What assignments are due this week?
Show me my current grades
What discussions do I need to respond to?

Instructors:

Which students haven't submitted the midterm?
Show me average scores for the last quiz
Create a discussion post about [topic] due next Friday

Administrators:

How many students are enrolled in Biology 101?
Show me course completion rates
List all active courses in the department

Troubleshooting

Standalone accounts

Error message:

Instance not properly configured: Your account is stand alone and is not integrated with Canvas.
It must be associated to an instance properly configured by your Teacher or Administrator.

Invalid or missing API URL

Symptom: Authentication fails or redirects to the wrong Canvas instance Error message:

Instance not properly configured: Access to Canvas LMS requires a valid Authorized Public URL
property for your instance! This value can be configured using the Administration UI.

Cause: The system cannot determine your institution’s Canvas domain, or there’s a mismatch in the authorized URLs configuration. Solution:

Check Authorized URLs

In your Digital Twin configuration, ensure the first line of your Public Authorized URLs contains your institution’s primary Canvas domain:

https://your-institution.instructure.com

Verify Domain Priority

The Canvas tools use the first domain in your authorized URLs list that contains .instructure.com or .edu. Order matters:Correct Order:

https://school.instructure.com
https://school.beta.instructure.com

The tools will use school.instructure.com (production)

Production vs. Test Instances: It is strongly recommended NOT to share a single Digital Twin between production and test Canvas instances. This can cause domain confusion and authentication failures.If you must use both environments, the Canvas tools will select the first domain in your authorized URLs list that contains either:

An .edu vanity domain (e.g., school.edu)
.instructure.com (Canvas cloud hosting)

Invalid or missing Client ID or Secret

Symptom: Error message about Client ID or Secret missing

Instance not properly configured: Access to Canvas LMS requires a valid Client Id for your
instance! This value can be configured using the Administration UI.

Instance not properly configured: Access to Canvas LMS requires a valid client secret for your
instance! This value can be configured using the Administration UI.

Solution:

Verify that you’ve copied the correct Client ID and Secret from Canvas
Ensure the Developer Key is enabled in Canvas
Check that the Redirect URI in Canvas matches: https://pria.praxislxp.com/api/auth/token_complete
Update your Digital Twin instance with the correct credentials

Invalid or missing course information

Error message:

Integration user issue: Access to Canvas LMS requires a valid course Id. Please launch from a
valid course page in your Canvas instance!

This happens when the Digital Twin has no course context — launch Pria from a course page (or a placement that passes the course id) so the tools know which course to query.

Insufficient Scopes Error

Error Message:

{
  "errors": [{
    "message": "Insufficient scopes on access token."
  }],
  "error_report_id": "1288266"
}

Example:

Access to Canvas LMS API function at https://institution.instructure.com/api/v1/courses/53493/assignments 
is Unauthorized (401). Insufficient scopes on access token.

Cause: The API endpoint being accessed requires a scope that hasn’t been authorized in your Canvas Developer Key. Solution:

Identify Required Scope

From the error message, note the endpoint path (e.g., /api/v1/courses/:course_id/assignments)

Add Scope in Canvas

Return to Canvas Developer Keys
Edit your Pria API key
Search for and enable the required scope
Save changes

Generate New Token

Users will need to re-authorize to receive a token with the updated scopes:

Log out of Praxis
Log back in
Re-authorize Canvas access when prompted

Important: When scopes are enforced, they must be defined in both locations:

Your Canvas Developer Key (authorizes the scopes)
Your Digital Twin configuration (declares required scopes)

Any modifications to the scope list require generating new access tokens, as scopes are embedded in the token at creation time.

Token Expiration Issues

Symptom: Frequent re-authorization requests or “token expired” messages Cause: Access tokens expire after 60 minutes of inactivity Solution: This is normal behavior. The system automatically refreshes tokens in the background. If you’re prompted to re-authorize:

Click the authorization link
Approve the request in Canvas
Continue your session

If you experience excessive re-authorization requests, check that your browser allows cookies from pria.praxislxp.com and your Canvas domain.

Removing Token

When scopes have changed and require a new token, or to simply re-issue a new authorization token:

Go to Profile

Click the Profile link in the top navigation menu.

Remove Token

Click the Remove Token button to remove your OAuth token for Canvas.

Issue New Token

To generate a new token, simply ask a question about content on Canvas and follow the OAuth2 authorization flow.

Canvas 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 only allows 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 (the Canvas Developer Key and your Digital Twin instance configuration), and both lists must match.

Canvas Scopes Reference

The complete scope reference — scope anatomy, common scopes by category, example use-case configurations, a starter JSON, best practices, and scope troubleshooting.

Smart Search

Canvas Smart Search provides an intelligent fallback mechanism when specific API endpoints are unavailable or return insufficient data due to scope restrictions.

What is Smart Search?

Smart Search is Canvas’s AI-powered search capability that allows natural language queries across course content, returning relevant results from:

Assignments and submissions
Discussion topics and posts
Pages and modules
Files and documents
Announcements
Quiz content

How the Canvas Tools Use Smart Search

The Canvas tools automatically fall back to Smart Search when:

Specific API endpoints lack required scopes
Direct API queries return no results
Complex cross-resource queries are needed
Natural language search provides better context

API Endpoint:

GET /api/v1/courses/:course_id/smartsearch

Required Scope:

url:GET|/api/v1/courses/:course_id/smartsearch

Official Documentation

For detailed information about Smart Search capabilities and parameters: Canvas Smart Search API Documentation

Availability and Requirements

Environment Availability: According to Canvas deployment notes, Smart Search is available only for Beta and Production releases. It may not be available in test or development Canvas instances.If you experience issues with Smart Search even after proper configuration, contact Instructure Support to verify that your Canvas instance has Smart Search enabled.

Best Practices

Recommended Configuration: Always include the Smart Search scope in your production configuration:

"url:GET|/api/v1/courses/:course_id/smartsearch"

This ensures your Digital Twin can gracefully handle edge cases and provide comprehensive search capabilities even when specific API scopes are restricted.

Additional Resources

Documentation Links

Support

For assistance with Canvas tools configuration or troubleshooting:

Search for help on the Canvas Community
Contact Praxis AI Support for Digital Twin configuration issues
Contact Instructure Support for Canvas-specific API or Smart Search availability questions

Community Examples

Explore real-world implementations and advanced use cases in the Praxis AI Community Repository:

​Overview

​Benefits and Use Cases

​For Students

​For Educators

​Advanced Capabilities

​How It Works

​Architecture

​Example Workflows

​Role-Based Access Control

​Automatic Role Detection

​Permission Levels

Students

Instructors

Administrators

​Security Model

​Getting Started

​Prerequisites

​Setup Overview

​Multi-Instance Management

​Create Developer Keys

​Step-by-Step Configuration

​Understanding Scope Enforcement

​Digital Twin Configuration

​Configuration Steps

​Testing Your Canvas Integration

​Initial Connection Test

​What to Test

​Troubleshooting

​Standalone accounts

​Invalid or missing API URL

​Invalid or missing Client ID or Secret

​Invalid or missing course information

​Insufficient Scopes Error

​Token Expiration Issues

​Removing Token

​Canvas Scopes

Canvas Scopes Reference

​Smart Search

​What is Smart Search?

​How the Canvas Tools Use Smart Search

​Official Documentation

​Availability and Requirements

​Best Practices

​Additional Resources

​Documentation Links

​Support

​Community Examples

Overview

Benefits and Use Cases

For Students

For Educators

Advanced Capabilities

How It Works

Architecture

Example Workflows

Role-Based Access Control

Automatic Role Detection

Permission Levels

Security Model

Getting Started

Prerequisites

Setup Overview

Multi-Instance Management

Create Developer Keys

Step-by-Step Configuration

Understanding Scope Enforcement

Digital Twin Configuration

Configuration Steps

Testing Your Canvas Integration

Initial Connection Test

What to Test

Troubleshooting

Standalone accounts

Invalid or missing API URL

Invalid or missing Client ID or Secret

Invalid or missing course information

Insufficient Scopes Error

Token Expiration Issues

Removing Token

Canvas Scopes

Smart Search

What is Smart Search?

How the Canvas Tools Use Smart Search

Official Documentation

Availability and Requirements

Best Practices

Additional Resources

Documentation Links

Support

Community Examples