OAuth & scopes

These appear during the Canvas OAuth "Connect Canvas" flow, or when the tool tries to use the Canvas API on someone's behalf.

A scope does not appear in the Developer Keys UI

Some Canvas environments do not surface every endpoint scope in the UI. This most often affects url:GET|/api/v1/login/session_token, which the SEB session handoff requires.

Fix:

Administrator-only scope additions do not invalidate ordinary instructor or student connections, and scope changes apply only to newly issued tokens. The full scope lists are in API OAuth key.

Instructor is asked to authorize repeatedly

The OAuth callback or key configuration does not match.

Fix — confirm all three:

• The API OAuth redirect URI exactly matches ${TOOL_URL}/api/oauth2callback.
• The OAuth key is enabled.
• The configured CANVAS_API_CLIENT_ID / CANVAS_API_CLIENT_SECRET are the API-key values — not the LTI key's.

If you changed the redirect URI or scope set, affected users must reauthorize once.

Student cannot connect Canvas or the configuration download fails

Usually a missing scope or a Canvas-environment mismatch.

Fix:

• Confirm the exact session_token scope is allowed on the API key.
• Confirm the student is authorizing the same Canvas environment as the LTI launch — connecting a different Canvas will not satisfy the launch.
• Have the student run the setup check to test the missing/revoked-scope recovery path, which requests a fresh Canvas connection.

Why every connection requests the same scopes

By design, every Canvas connection requests the same complete application scope set regardless of the user's role in the initiating course. This keeps one durable grant valid for someone who is an instructor in one course and a student in another. Canvas still enforces their actual permissions, so a broad scope request does not grant broad access — it only avoids incompatible role-specific grants. An administrator's grant is the same record, upgraded in place with the account scopes.

Where tokens live

One OAuth grant is stored per Canvas user in canvas_oauth_tokens; the service refreshes it as needed, and a 401 from Canvas triggers at most one safe refresh/retry. If authorization is badly wedged for one user, having them Reconnect Canvas issues a fresh grant. Rotating STATE_ENCRYPTION_KEY invalidates in-flight OAuth state (not stored grants) — see Configuration → Secret rotation.