Authentication Guide¶

Canvas CLI supports multiple authentication methods: API Token (simplest), OAuth 2.0 (most secure), and Environment Variables (for CI/CD). This guide covers everything you need to set up and manage authentication.

Quick Start¶

Option 1: API Token (Simplest)¶

canvas auth token set myschool --url https://canvas.instructure.com --token 7~your-token-here

Generate a token in Canvas: Account > Settings > New Access Token

Option 2: OAuth 2.0 (Most Secure)¶

canvas auth login --instance https://canvas.instructure.com

This will open your browser to authorize the application.

API Token Authentication¶

API tokens are the simplest way to authenticate, especially for personal use or when OAuth isn't required.

Getting an API Token¶

Log into Canvas
Go to Account > Settings
Scroll to Approved Integrations
Click + New Access Token
Give it a name and set an expiration (optional)
Copy the token (it will only be shown once!)

Setting Up Token Auth¶

# For an existing instance
canvas auth token set myschool --token 7~abc123...

# For a new instance (include URL)
canvas auth token set sandbox --url https://sandbox.instructure.com --token 7~xyz789...

# Interactive mode (prompts for token)
canvas auth token set myschool

Managing Tokens¶

# Check authentication status (shows auth type)
canvas auth status

# Remove token from an instance
canvas auth token remove myschool

Mixing Auth Types¶

You can use different authentication methods for different instances:

# OAuth for production
canvas auth login --instance prod

# Token for sandbox/testing
canvas auth token set sandbox --url https://sandbox.instructure.com --token 7~test123...

# Check status - shows auth type for each
canvas auth status

Output:

📌 prod (default)
   URL: https://canvas.instructure.com
   Auth: OAuth
   Status: ✓ Authenticated

📌 sandbox
   URL: https://sandbox.instructure.com
   Auth: API Token
   Status: ✓ Configured (token does not expire)

OAuth 2.0 Setup¶

Step 1: Create a Developer Key (Optional)¶

By default, Canvas CLI uses embedded OAuth credentials. For enhanced security or custom integrations, you can create your own:

Log into Canvas as an administrator
Navigate to Admin > Developer Keys
Click + Developer Key > + API Key
Fill in the details:
Key Name: Canvas CLI
Owner Email: your-email@example.com
Redirect URIs: http://localhost:8080/callback (or your preferred port)
Scopes: Select all required scopes
Save and note your Client ID and Client Secret

Step 2: Authenticate¶

Using Embedded Credentials (Easiest)¶

canvas auth login --instance https://canvas.instructure.com

Using Your Own Credentials¶

canvas auth login \
  --instance https://canvas.instructure.com \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

Step 3: Verify Authentication¶

# Check authentication status
canvas auth status

# Test with a simple API call
canvas courses list

Authentication Methods¶

Local Browser Flow (Default)¶

The CLI starts a local web server and opens your browser:

canvas auth login --instance https://canvas.instructure.com

This is the most user-friendly method and works on most systems.

Out-of-Band (OOB) Flow¶

For systems without a browser or remote SSH sessions:

canvas auth login --instance https://canvas.instructure.com --mode oob

This will: 1. Display an authorization URL 2. Ask you to visit it manually 3. Prompt you to paste the authorization code

Environment Variables (CI/CD)¶

For automated workflows and CI/CD pipelines, Canvas CLI supports authentication via environment variables:

# Required environment variables
export CANVAS_URL="https://canvas.instructure.com"
export CANVAS_TOKEN="your-access-token"

# Optional: Control rate limiting (default: 5.0)
export CANVAS_REQUESTS_PER_SEC="10.0"

# Commands will use these automatically
canvas courses list

How to get your access token:

Log into Canvas
Go to Account > Settings > Approved Integrations
Click + New Access Token
Copy the token (it will only be shown once)

Priority Order:

Canvas CLI checks for credentials in this order:

Environment variables (CANVAS_URL + CANVAS_TOKEN) - highest priority
API Token in config (set via canvas auth token set)
OAuth tokens (stored in system keychain, set via canvas auth login)

CI/CD Example (GitHub Actions):

name: Canvas CI
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Canvas CLI
        env:
          CANVAS_URL: ${{ secrets.CANVAS_URL }}
          CANVAS_TOKEN: ${{ secrets.CANVAS_TOKEN }}
        run: |
          canvas courses list
          canvas assignments list --course-id 123

Multi-Instance Management¶

Canvas CLI supports multiple Canvas installations:

Add Multiple Instances¶

# Add production instance
canvas config add production --url https://canvas.instructure.com

# Add staging instance
canvas config add staging --url https://staging.canvas.instructure.com

# Add self-hosted instance
canvas config add onprem --url https://canvas.company.com

Switch Between Instances¶

# List all instances
canvas config list

# Switch to a different instance
canvas config use staging

# Use a specific instance for one command
canvas courses list --instance production

Authenticate Each Instance¶

# Authenticate with each instance separately
canvas auth login --instance production
canvas auth login --instance staging
canvas auth login --instance onprem

Credential Storage¶

Canvas CLI stores credentials securely using your system's native keychain:

macOS: Keychain
Linux: Secret Service API (gnome-keyring, kwallet)
Windows: Windows Credential Manager

Fallback Storage¶

If keychain access fails, credentials are stored in encrypted files:

Location: ~/.canvas-cli/credentials.enc
Encryption: AES-256-GCM with machine-specific key
Key Derivation: Machine ID + username

Manual Credential Management¶

# View stored credentials (won't show tokens)
canvas auth status

# Logout (removes credentials)
canvas auth logout

# Logout from specific instance
canvas auth logout --instance staging

# Logout from all instances
canvas auth logout --all

Token Management¶

Token Refresh¶

Access tokens expire after 1 hour. Canvas CLI automatically refreshes them using refresh tokens.

Token Permissions (Scopes)¶

Canvas CLI requests the following OAuth scopes:

url:GET|/api/v1/courses - Read courses
url:POST|/api/v1/courses - Create courses
url:PUT|/api/v1/courses/:id - Update courses
url:DELETE|/api/v1/courses/:id - Delete courses
Similar patterns for assignments, submissions, users, files

Manual Token Usage¶

If you have an access token, use environment variables:

# Set environment variables
export CANVAS_URL="https://canvas.instructure.com"
export CANVAS_TOKEN="YOUR_ACCESS_TOKEN"

# Commands will use these automatically
canvas courses list

Security Best Practices¶

1. Use System Keychain¶

Always allow Canvas CLI to use your system keychain when prompted.

2. Rotate Tokens Regularly¶

# Logout and login again to get fresh tokens
canvas auth logout
canvas auth login

3. Limit Scope¶

When creating developer keys, only grant necessary scopes.

4. Use Environment Variables for CI/CD¶

For automated systems, use environment variables instead of storing credentials in code:

# Example GitHub Actions workflow
env:
  CANVAS_URL: ${{ secrets.CANVAS_URL }}
  CANVAS_TOKEN: ${{ secrets.CANVAS_TOKEN }}

5. Keep Credentials Private¶

Never commit tokens or credentials to version control:

# Add to .gitignore
echo ".canvas-cli/" >> .gitignore

Troubleshooting¶

"Failed to open browser"¶

Use OOB flow:

canvas auth login --instance https://canvas.instructure.com --mode oob

"Failed to access keychain"¶

Grant permission in system settings or use encrypted file storage (automatic fallback).

"Token expired"¶

Tokens refresh automatically. If refresh fails:

canvas auth logout
canvas auth login

"Unauthorized" or "403 Forbidden"¶

Check your OAuth scopes or Canvas permissions:

canvas auth status

"CORS errors"¶

Ensure your Canvas instance allows OAuth from localhost: - Check Developer Key redirect URIs - Verify Canvas OAuth settings

Advanced Configuration¶

Force OOB Mode¶

For headless servers or SSH sessions without X forwarding:

canvas auth login --instance https://canvas.instructure.com --mode oob

Verbose Output¶

For troubleshooting authentication issues:

canvas auth login --instance https://canvas.instructure.com --verbose

Next Steps¶

After authentication: - Command Reference - Learn available commands - Tutorials - See common use cases - Test your setup: canvas courses list