DEV Community: Sharon Wang

The Missing Guide to Canvas LMS OAuth 2.0 Integration

Sharon Wang — Fri, 11 Sep 2026 13:32:16 +0000

The OAuth 2.0 protocol provides a secure mechanism for a third-party application (the Client) to access user information stored in Canvas LMS without requiring the user to share their Canvas credentials directly.

When an instructor links their account with a third-party application, they are redirected to the Canvas SSO login page. Upon successful authentication and consent, the application is granted authorized access to the instructor's Canvas data. This linked state enables core integrations, such as importing student rosters and exporting grades seamlessly.

Terminology Reference

Understanding OAuth 2.0 requires defining the specific roles each system component plays:

Term	Definition & Context
Resource Owner	The end-user (e.g., the instructor) who grants access to their data.
Client	Your application requesting access to the user's information.
Authorization Server	The system that authenticates the user and issues access tokens. Canvas LMS acts as the authorization server.
Authorization Grant	A credential representing the resource owner's consent. The client exchanges this grant for an access token.
Access Token (Bearer)	The secure key used by the client to access protected resources on behalf of the user.
Resource Server	The system hosting the protected user accounts and information. It verifies the access token before responding.
Redirect URI	The pre-registered destination where the authorization server sends the user after granting consent.
Scope	The specific permissions granted by the end-user (e.g., reading course lists, fetching enrollments).
Client ID & Secret	The unique credentials used to identify and authenticate your application to the authorization server.

Authorization Code Flow

Canvas LMS implements the Authorization Code Flow, which is the most common and secure OAuth 2.0 flow for server-side applications. The process is divided into front-channel (browser-based) and back-channel (server-to-server) communications.

Sequence Diagram

sequenceDiagram
    participant User as Resource Owner (Instructor)
    participant Client as Client Application
    participant AuthServer as Authorization Server (Canvas)
    participant ResourceServer as Resource Server (Canvas)

    Note over User, AuthServer: Front-Channel Flow
    User->>Client: Initiates account linking
    Client->>User: Redirects to Canvas Authorization URL
    User->>AuthServer: Enters credentials & grants consent
    AuthServer->>User: Redirects to Client Redirect URI with Auth Code
    User->>Client: Passes Auth Code via Redirect

    Note over Client, ResourceServer: Back-Channel Flow
    Client->>AuthServer: POST Auth Code, Client ID, Client Secret
    AuthServer-->>Client: Returns Access Token & Refresh Token
    Client->>ResourceServer: API Request + Access Token
    ResourceServer-->>Client: Returns Requested Data

1. Requesting User Consent (Front-Channel)

To begin the flow, your application redirects the user's browser to the Canvas authorization endpoint:
GET https://<canvas-instance>/login/oauth2/auth

Include the following query parameters:

client_id: Your application's unique ID.
response_type: Set to code.
redirect_uri: The endpoint in your application that will handle the callback.
scope: (Optional) A space-separated list of required scopes.

The user logs into Canvas and is prompted to authorize the application. Upon consent, Canvas redirects the user back to the redirect_uri, appending a temporary authorization code to the URL query string (?code=...).

2. Exchanging the Code for a Token (Back-Channel)

Your application extracts the authorization code and securely sends a background POST request to the Canvas token endpoint:
POST https://<canvas-instance>/login/oauth2/token

Include the following URL‑encoded form data (not JSON):

grant_type=authorization_code
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
redirect_uri=YOUR_REDIRECT_URI
code=AUTHORIZATION_CODE_FROM_REDIRECT

Note: Replace <canvas-instance> throughout this guide with the actual domain of your Canvas LMS instance (e.g., canvas.instructure.com).

Canvas validates the credentials and returns a JSON response containing the access_token, a refresh_token, and the expires_in duration (typically 3600 seconds).

3. Making Authenticated API Requests

Your application stores these tokens securely and utilizes the access_token in the Authorization header of subsequent API requests to the Canvas Resource Server.

GET /api/v1/courses HTTP/1.1
Host: <canvas-instance>
Authorization: Bearer <access_token>

4. Refreshing Expired Tokens

Access tokens possess a limited lifespan. Before making API calls, your application should validate the token's temporal validity. If the token is expired, issue a refresh request to the token endpoint:
POST https://<canvas-instance>/login/oauth2/token

Include the following payload:

grant_type: Set to refresh_token.
client_id: Your application's unique ID.
client_secret: Your application's secure secret key.
refresh_token: The refresh token received in step 2.

Upon success, the new access_token and updated expiration timestamp should be persisted to your database.

Example HTTP Request (cURL)

To execute the back-channel token exchange, you can make a standard POST request to the token endpoint.

Because the OAuth 2.0 specification requires token requests to be formatted as form data (rather than JSON), ensure you use the -d flag in your curl command to send the payload as application/x-www-form-urlencoded.

curl -X POST https://canvas.instructure.com/login/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://api.your-app.com/oauth/callback" \
  -d "code=AUTHORIZATION_CODE_FROM_REDIRECT"

Example Response:

{
  "access_token": "8489~TOKEN_STRING",
  "token_type": "Bearer",
  "user": {
    "id": 12345,
    "name": "Jane Doe"
  },
  "refresh_token": "8489~REFRESH_TOKEN_STRING",
  "expires_in": 3600
}

Zero to Running: Setting up a Canvas LMS Dev Environment with Docker on AWS EC2

Sharon Wang — Fri, 11 Sep 2026 13:24:13 +0000

This runbook outlines the manual infrastructure provisioning process used strictly for initial integration testing. While manual setup is sufficient for early staging, a production-grade Developer Experience (DevEx) implementation would automate this using EC2 user-data scripts or Terraform to bootstrap the Mutagen containers on launch—eliminating the need for developers to manually SSH into the instance or manage server security concerns.

Prerequisites

If you need to provision a Canvas instance from scratch rather than using the existing pre-configured AWS server, ensure the host machine has the following dependencies installed:

Caution: Environment Variances
Installation commands vary based on the host operating system (e.g., using yum on Amazon Linux versus apt-get on Ubuntu/Debian). Furthermore, Canvas is highly memory-intensive; ensure your EC2 instance is sufficiently provisioned to avoid out-of-memory (OOM) crashes. Ensure all necessary firewall ports are open for HTTP/HTTPS traffic.

For a comprehensive from-scratch installation guide, refer to the Canvas LMS GitHub Repository Quick Start.

1. Starting the Canvas Instance

Follow these steps to boot the pre-configured Canvas testing environment on AWS:

1. SSH into the Host Server: Connect to your designated EC2 instance. You can find the public IPv4 address for the testing server in the AWS EC2 dashboard.

2. Clone the Canvas LMS Source Repository:

git clone https://github.com/instructure/canvas-lms.git

3. Navigate to the Repository:

cd canvas-lms

4. Initialize the Dev Setup (First Time Only): If the instance is not already running, execute the setup script.

./script/docker_dev_setup.sh

Note: This process takes significant time. When prompted to create an administrator account, provide a testing email address.

5. Start the Containers: Spin up the Docker stack using Mutagen.

mutagen-compose up -d

6. Verify Container Health: Ensure all containers booted successfully.

docker ps -a

7. Access the Web Interface: Replace <EC2_PUBLIC_IPV4_ADDRESS> with the actual public IPv4 address of your EC2 instance. Open your browser and navigate to http://<EC2_PUBLIC_IPV4_ADDRESS>. Log in using the testing credentials established during step 4.

2. Generating the OAuth Developer Key

To allow your application to communicate with Canvas, you must register it as an authorized client application.

Navigate to Developer Keys: Within the Canvas web interface, click Admin > Site Admin > Developer Keys from the left sidebar.
Create a New Key: Click + Developer Key > + API Key.
Configure Key Parameters:
- Key Name: Local Integration Testing
- Owner Email: Enter your designated testing admin email.
- Redirect URIs: Enter your application's OAuth callback URL (e.g., https://api.your-app.com/oauth/callback).
- Redirect URI (Legacy): (Enter the same URI as above to prevent legacy routing issues).
Enforce Scopes: Toggle Enforce Scopes and select the specific API endpoints required by your application.
Save and Extract Credentials: Click Save Key. The system will generate two critical values:
- Client ID: The numerical string visible under the "Details" column.
- Client Secret: Click Show Key to reveal the alphanumeric secret. Store these securely.

Your Canvas instance is now actively running and configured to accept OAuth 2.0 requests from your client application!