Request a Canvas API token

On this page:


About Canvas API tokens

Important:
The Canvas API proxy service was decommissioned on June 25, 2020. If you previously used a proxy token to access the Canvas API, you'll need to request a new token.

Canvas has a robust API that can be used to retrieve, create, edit, and delete Canvas data. If you want to use the API, you must request an access token for the Canvas API.

Access tokens grant you the same level of access as you normally have in Canvas. For example, if you are an instructor, your token will allow you to retrieve, add, update, and delete data in your own classes via the API, but you will not have access to classes in which you are not enrolled.

Request an API token

  1. Log into Canvas and, on the left, click Account.
  2. In the resulting Account menu, click Settings.
  3. Click New Access Token.
  4. In the Canvas API Token Request form, fill out all required information. Be sure to give detailed information under "For what purpose do you need a Canvas API token?" Access tokens will not be issued without clear information about how the token will be used.
  5. Once you've filled out the form, click Submit. Canvas administrators will review your request, and you may be contacted if more details are needed.
  6. When the review is complete, you'll receive a notification with the status of your request. If approved, the Canvas administrator will transmit your tokens to you via Secure Share. You'll receive a token for Canvas production, which will work in the beta environment the Monday after it was issued. The token can be used in the test environment after test is refreshed, which is every four weeks.

    Canvas refresh schedule

Access the Canvas API

In order to use the token, your API calls or scripts must include two custom headers, an authorization header and a content type header. Set up each header using the values below:

Name Value
Authorization header Authorization
Bearer [your_token]
(There is a space between Bearer and your token.)
Content type header Content-Type application/json

Canvas production instance: https://iu.instructure.com

Important:

Exercise caution when taking any action that modifies data in Canvas. UITS recommends testing your API calls and scripts in IU's test or beta environment for Canvas. The test environment has the same code base as production, while Canvas beta includes code for features that have not yet been released. To access these environments, use:

  • Canvas test instance: https://iu.test.instructure.com
  • Canvas beta instance: https://iu.beta.instructure.com

Special characters in API calls

If you are including parameters with the API calls, depending on the tools or language used, you may need to encode special characters such as brackets ([ ]).

For example, consider the following:

https://iu.beta.instructure.com/api/v1/courses?include[]=term

You may need to change include[] to include%5B%5D:

https://iu.beta.instructure.com/api/v1/courses?include%5B%5D=term

Some REST clients (for example, Postman, Insomnia) encode the calls automatically, so escaping special characters is not necessary.

For more about encoding, see:

This is document aaja in the Knowledge Base.
Last modified on 2023-07-13 11:18:31.