Request a Canvas API token

On this page:


About Canvas API tokens

Canvas has a robust API that can be used to retrieve, create, edit, and delete Canvas data. End users may not access the API directly. Instead, Indiana University has deployed a proxy server through which all API requests are routed. If you want to use the API, you must request a token for the proxy server.

Proxy tokens grant you the same level of access as you normally have in Canvas. For example, if you are an instructor, your proxy 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 Slashtmp. You'll receive separate tokens for the Canvas production, test, and beta environments; a token will only work on the environment for which it was created. For more about the test and beta environments, see below.

Access the Canvas API via the proxy server

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 X-IU-Authorization
[your_token]
(Use the entire string, including the front portion which contains your name, for [your_token].)
Content type header Content-Type application/json

When making an API request through IU's proxy server, replace the endpoint prefix for direct API access with the prefix in the right-hand column of the following table.

Direct API access
API access via the proxy server
Prefix
https://iu.instructure.com/api/v1/
https://lmsproxy.uits.iu.edu/lmspx-prd/canvas/
Sample request
https://iu.instructure.com/api/v1/courses
https://lmsproxy.uits.iu.edu/lmspx-prd/canvas/courses
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
    • Direct access: https://canvas-test.iu.edu
    • Proxy prefix: https://lmsproxy-test.uits.iu.edu/lmspx-stg/canvas/
  • Canvas beta instance
    • Direct access: https://canvas-beta.iu.edu
    • Proxy prefix: https://lmsproxy-beta.uits.iu.edu/lmspx-reg/

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://lmsproxy-beta.uits.iu.edu/lmspx-reg/canvas/courses?include[]=term

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

https://lmsproxy-beta.uits.iu.edu/lmspx-reg/canvas/courses?include%5B%5D=term

Some REST clients (e.g., 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 2018-07-24 12:30:47.

Contact us

For help or to comment, email the UITS Support Center.