GET https://<canvas-install-url>/login/oauth2/auth?client_id=XXX&response_type=code&redirect_uri=https://example.com/oauth_complete&state=YYY

Parameters

Parameter	Description
client_id	The client id for your registered application.
response_type	The type of OAuth2 response requested. The only currently supported value is code.
redirect_uri	The URL where the user will be redirected after authorization. The domain of this URL must match the domain of the redirect_uri stored on the developer key, or it must be a subdomain of that domain. For native applications, currently the only supported value is urn:ietf:wg:oauth:2.0:oob, signifying that the credentials will be retrieved out-of-band using an embedded browser or other functionality.
state	Your application can pass Canvas an arbitrary piece of state in this parameter, which will be passed back to your application in Step 2. It's strongly encouraged that your application pass a unique identifier in the state parameter, and then verify in Step 2 that the state you receive back from Canvas is the same expected value. Failing to do this opens your application to the possibility of logging the wrong person in, as described here.
scope	This can be used to specify what information the access token will provide access to. A complete list of available scopes can be found here. Scopes may also be found beneath their corresponding endpoints in the "resources" documentation pages. If the developer key does not require scopes and no scope parameter is specified, the access token will have access to all scopes. If the developer key does require scopes and no scope parameter is specified, Canvas will respond with "invalid_scope."
purpose	This can be used to help the user identify which instance of an application this token is for. For example, a mobile device application could provide the name of the device.
force_login	Set to '1' if you want to force the user to enter their credentials, even if they're already logged into Canvas. By default, if a user already has an active Canvas web session, they will not be asked to re-enter their credentials.
unique_id	Set to the user's username to be populated in the login form in the event that the user must authenticate.

See Section 4.1.3 of the OAuth2 RFC for more information about this process.

POST /login/oauth2/token

Parameters

Parameter	Description
grant_type	Values currently supported "authorization_code", "refresh_token"
client_id	The client id for your registered application.
client_secret	The client secret for your registered application.
redirect_uri	If a redirect_uri was passed to the initial request in step 1, the same redirect_uri must be given here.
code grant_type: authorization_code	Required if grant_type is authorization_code. The code you received in a redirect response.
refresh_token grant_type: refresh_token	Required if grant_type is refresh_token. The refresh_token you received in a redirect response.

Example responses

When using grant_type=code:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "token_type": "Bearer",
    "user": {"id":42, "name": "Jimi Hendrix"},
    "refresh_token": "tIh2YBWGiC0GgGRglT9Ylwv2MnTvy8csfGyfK2PqZmkFYYqYZ0wui4tzI7uBwnN2",
    "expires_in": 3600
  }
  

When using grant_type=refresh_token, the response will not contain a new refresh token since the same refresh token can be used multiple times:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "token_type": "Bearer",
    "user": {"id":42, "name": "Jimi Hendrix"},
    "expires_in": 3600
  }
  

If scope=auth/userinfo was specified in the GET login/oauth2/auth request then the response that results from POST login/oauth2/token would be:

  {
    "access_token": null,
    "token_type": "Bearer",
    "user":{"id": 42, "name": "Jimi Hendrix"}
  }
  

Parameter	Description
access_token	The OAuth2 access token.
token_type	The type of token that is returned.
user	A JSON object of canvas user id and user name.
refresh_token	The OAuth2 refresh token.
expires_in	Seconds until the access token expires.

If your application supports logout functionality, you can revoke your own access token. This is useful for security reasons, as well as removing your application from the list of tokens on the user's profile page. Simply make an authenticated request to the following endpoint by including an Authorization header or providing the access_token as a request parameter.

DELETE /login/oauth2/token

Parameters

Parameter	Description
expire_sessions	Set this to '1' if you want to end all of the user's Canvas web sessions. Without this argument, the endpoint will leave web sessions intact.

If your application needs to begin a normal web session in order to access features not supported via API (such as quiz taking), you can use your API access token in order to get a time-limited URL that can be fed to a browser or web view to begin a new web session.

GET /login/session_token

Parameters

Parameter	Description
return_to	An optional URL to begin the web session at. Otherwise the user will be sent to the dashboard.

Example responses

  {
    "session_url": "https://canvas.instructure.com/opaque_url"
  }