OAuth2 with the LMS API
Make sure you've read about authenticating API requests before proceeding to the guide below.
The OAuth2 API endpoints only accept the bearer api key based authentication method.
The LTI® protocol covers launches, deep linking, grades, and rosters, but not every operation a tool might need. Some LMSes — most notably Canvas and Brightspace (D2L) — expose a native REST API that goes well beyond the LTI® surface, with endpoints for listing course files, manipulating enrollments, reading non-graded content, posting announcements, and many other operations. These APIs are protected by standard OAuth2 and act on behalf of an individual LMS user, with the user's explicit consent. If your tool needs functionality beyond what the LTI® services provide, complementing LTI® with OAuth2 is the way to go.
LTIAAS gives you access to the OAuth2 handshake through the /oauth/start/:platformId and /api/oauth/access-token/:platformId endpoints. LTIAAS handles redirecting the user to the LMS, accepting the LMS's callback, and exchanging the LMS's authorization code for an access token, so that your application never has to mint its own OAuth client, manage state cookies across the redirect chain, or store the LMS's signing keys. The resulting access token is a Bearer token that your application uses directly against the LMS's REST API.
OAuth2 is a paid add-on. Before you start wiring it up, make sure your LTIAAS plan includes OAuth2 support, or upgrade your existing plan.
LMS administrator creates a developer key for your tool
Step 1 of 7OAuth2 needs to be registered with the LMS just like an LTI® tool does. The LMS administrator opens whichever page their LMS provides for creating an API key — Canvas calls it Admin → Developer Keys → API Key; Brightspace exposes it under Manage Extensibility → OAuth 2.0 — and configures a new key for your tool. The most important field is the redirect URI, which must point at your LTIAAS subdomain:
https://your.ltiaas.com/oauth/complete
The LMS administrator also chooses the scopes your tool will be allowed to request. Some LMS administrators enforce a strict allowlist of scopes, so it's important to communicate clearly which endpoints your tool plans to call, so they can enable the matching scopes. Once the key is saved, the LMS surfaces a Client ID and Client Secret that the administrator passes back to you.
It's recommended to publish, alongside your tool's documentation, a short page listing every scope your tool may request. Mismatched scopes are a common source of mystifying 403 responses, and giving LMS administrators a clear allowlist up front prevents most of those tickets.
For the LMS-specific instructions for Canvas, see the Full OAuth2 setup walkthrough in the OAuth2 guide.
What's next
- Launch + idtoken SSO flow — the typical entry point that establishes a user in your tool before they connect via OAuth.
- Names & Roles flow — for most roster needs, NRPS is simpler than OAuth2. Reach for OAuth2 only when you need functionality that LTI® does not expose.
- Grade Passback flow — for standard grading, the AGS service is enough; OAuth2 is only needed for the LMS's advanced gradebook features.
