OAuth

OAuth2 is a protocol designed to let third-party applications authenticate to perform actions as a user, without getting the user's password. Canvas uses OAuth2 for authentication and authorization of the Canvas API. HTTP Basic Auth is deprecated and will be removed.

Authenticating a Request

Once you have an OAuth access token, you can use it to make API requests. If possible, using the HTTP Authorization header is recommended. Sending the access token in the query string or POST parameters is also supported.

OAuth2 Token sent in header:

curl -H "Authorization: Bearer <ACCESS-TOKEN>" https://canvas.instructure.com/api/v1/courses

OAuth2 Token sent in query string:

curl https://canvas.instructure.com/api/v1/courses?access_token=<ACCESS-TOKEN>

Storing Tokens

When appropriate, applications should store the token locally, rather the requesting a new token for the same user each time the user uses the application. If the token is deleted or expires, the application will get a 401 Unauthorized error from the API, in which case the application should perform the OAuth flow again to receive a new token.

Storing a token is in many ways equivalent to storing the user's password, so tokens should be stored and used in a secure manner, including but not limited to:

• Don't embed tokens in web pages.
• Don't pass tokens or session IDs around in URLs.
• Properly secure the database or other data store containing the tokens.
• For web applications, practice proper techniques to avoid session attacks such as cross-site scripting, request forgery, replay attacks, etc.
• For native applications, take advantage of user keychain stores and other operating system functionality for securely storing passwords.

Manual Token Generation

If your application only needs to access the API as a single user, the simplest option is to generate an access token on the user's profile page.

1. Click the "profile" link in the top right menu bar, or navigate to /profile
2. Under the "Approved Integrations" section, click the button to generate a new access token.
3. Once the token is generated, you cannot view it again, and you'll have to generate a new token if you forget it. Remember that access tokens are password equivalent, so keep it secret.

Logging Out

Oauth2 Based Identity Service

Your application can rely on canvas for a user's identity. During step 1 of the web application flow below, specify the optional scopes parameter as scopes=/auth/userinfo. When the user is asked to grant your application access in step 2 of the web application flow, they will also be given an option to remember their authorization. If they grant access and remember the authorization, Canvas will skip step 2 of the request flow for future requests.

Canvas will not give a token back as part of a userinfo request. It will only provide the current user's name and id.

OAuth2 Token Request Flow

If your application will be used by others, you will need to implement the full OAuth2 token request workflow, so that you can request an access token for each user of your application.

Performing the OAuth2 token request flow requires an application client ID and client secret. To obtain these application credentials, you will need to register your application. The client secret should never be shared.

For Canvas Cloud, you can request a client ID and secret from http://www.instructure.com/partners , or contact your account representative.

For open source Canvas users, you can generate a client ID and secret in the Site Admin account of your Canvas install. There will be a "Developer Keys" tab on the left navigation sidebar.

Web Application Flow

This is the OAuth flow for third-party web applications.

Step 1: Redirect users to request Canvas access

Step 2: Redirect back to the request_uri, or out-of-band redirect

If the user accepts your request, Canvas redirects back to your request_uri with a specific query string, containing the OAuth2 response:

The app can then extract the code, and use it along with the clientid and clientsecret to obtain the final access_key.

If the user doesn't accept the request for access, or if another error occurs, Canvas redirects back to your request_uri with an error parameter, rather than a code parameter, in the query string.

access_denied is the only currently implemented error code.

Step 3: Exchange the code for the final access token

{
  access_token: "1/fFAGRNJru1FTz70BzhT3Zg",
}

Native Application Flow

This is the OAuth flow for desktop client and mobile applications. The application will need to embed a web browser view in order to detect and read the out-of-band code response.

Step 1: Redirect users to request Canvas access

Step 2: Redirect back to the request_uri, or out-of-band redirect

If the user accepts your request, Canvas redirects back to your request_uri (not yet implemented), or for out-of-band redirecting, to a page on canvas with a specific query string, containing the OAuth2 response:

At this point the app should notice that the URL of the webview has changed to contain code=<code> somewhere in the query string. The app can then extract the code, and use it along with the clientid and clientsecret to obtain the final access_key.

If the user doesn't accept the request for access, or if another error occurs, Canvas will add an error parameter, rather than a code parameter, to the query string.

access_denied is the only currently implemented error code.

Step 3: Exchange the code for the final access token

{
  access_token: "1/fFAGRNJru1FTz70BzhT3Zg",
}