Canvas setup: API connection (OAuth)

The API connection is an OAuth developer key, configured once for the organisation. Each user then authorises Raison with their own Canvas account, and sees only the courses that account already gives them access to. Canvas remains responsible for those permissions.

Raison no longer uses a personal API token. If your organisation was set up with the legacy token, replace it with the OAuth application below.

Depending on your Canvas configuration, the account menu may display your institution's name instead of "Canvas".

Official Canvas documentation: Configuring LTI Advantage tools.

Create an API developer key in Canvas

Sign in to Canvas as an administrator, or as a user who can manage developer keys.
Go to Admin → Your Canvas account → Developer Keys.
Select + Developer Key → + API Key.

Field	Recommended value
Key Name	`Raison API`
Owner Email	`[email protected]`

Both fields only help administrators identify the integration later.

Add the OAuth callback URL

Paste this into the Redirect URIs field in Canvas:

https://services.raison.is/integration/canvas/v2/oauth/callback

You can also copy it from Raison under Organization → Integrations → Canvas → Configure → OAuth API Key, field OAuth callback URL.

Copy the URL exactly. A missing character, an extra space, or a trailing / will cause Canvas to reject the authorisation with an invalid redirect URL error.

Configure the scopes

Enable Enforce Scopes.

The simplest option is to enable all available read-only scopes. For stricter control, select only the 12 read-only scopes Raison actually calls:

Canvas API scope	Purpose
`url:GET\\|/api/v1/courses`	Lists the courses available to the authenticated Canvas user.
`url:GET\\|/api/v1/courses/:id`	Retrieves information about a specific course.
`url:GET\\|/api/v1/courses/:course_id/modules`	Lists the modules in a course.
`url:GET\\|/api/v1/courses/:course_id/modules/:id`	Retrieves information about a specific module.
`url:GET\\|/api/v1/courses/:course_id/modules/:module_id/items`	Lists the items inside a module, including linked pages and files.
`url:GET\\|/api/v1/courses/:course_id/modules/:module_id/items/:id`	Retrieves information about a specific module item.
`url:GET\\|/api/v1/courses/:course_id/files`	Lists the files associated with a course.
`url:GET\\|/api/v1/files/:id`	Retrieves file information and its authorized download URL.
`url:GET\\|/api/v1/courses/:course_id/pages`	Lists the pages in a course.
`url:GET\\|/api/v1/courses/:course_id/pages/:url_or_id`	Retrieves the content of a specific Canvas page.
`url:GET\\|/api/v1/courses/:course_id/users`	Lists the users enrolled in a course.
`url:GET\\|/api/v1/courses/:course_id/folders`	Lists the folders in a course, so files can be shown in their Canvas folder hierarchy rather than as a flat list.

All scopes are read-only. Raison never requests permission to modify or delete Canvas content.

The folders scope is newer than the original integration. If a key was created without it, add it in Canvas. Until you do, Raison retries without that scope and files import as a flat list.

Save and enable the key

Save the key, find it in the Developer Keys list, and switch it On in the State column. The key must be enabled before Raison can use it.

Copy the credentials into Raison

In Canvas, in the Details column of the key:

the numeric identifier is the Client ID
Show Key reveals the Client Secret

In Raison, go to Organization → Integrations → Canvas → Configure → OAuth API Key and fill in:

Field	What to enter	Fixed or specific?
Canvas URL	The base URL of your Canvas instance, e.g. `https://canvas.your-institution.com`. No path such as `/admin`, `/courses`, or `/login`	Specific to your institution
Client ID	The numeric ID of the API developer key	Specific to your Canvas instance
Client secret	The value revealed by Show Key	Specific to your Canvas instance

Select Save OAuth application.

Treat the Client Secret like a password. Never put it in screenshots, emails, or support requests.

Test the API connection

Use Connect and test course access in Raison, or go to the dashboard and select Quick create → Canvas. A Canvas authorisation window opens. Sign in, approve, and your Canvas courses should appear in Raison.

Each instructor authorises Canvas with their own account the first time they import content, so the courses they see always respect their own Canvas scope.

The API connection imports content. To open the assistant inside Canvas, also configure Canvas setup: LTI 1.3.

API checklist

The API developer key is enabled in Canvas
The OAuth callback URL matches exactly
Enforce Scopes is on and the read-only scopes are selected
Canvas URL, Client ID, and Client secret are saved in Raison
Canvas courses appear when using Quick create → Canvas

Need help? Write to [email protected].