Your Community is getting an upgrade!
Read about our partnership with Higher Logic and how we will build the next generation of the Instructure Community.
Found this content helpful? Log in or sign up to leave a like!
Hello everyone, I hope you are doing well. I figured I would post this question here as I didn't find anything similar in searching online. I am an admin for a canvas course that can generate API tokens and access the API this way. Recently, I have been trying to write some custom Javascript for my theme to detect a student's section. That is the only data that I really want to be pulled when a student is viewing the course so that content can change dynamically depending on whether they are enrolled in a particular section.
The odd thing that I just discovered is that as a student, I am able to call a GET requests through https://[instancename].instructure.com/api/v1/courses/[courseid]/enrollments?user_id=[studentid] by just going there in the URL while logged in as a non admin student. So I thought hmm what if I called it through fetch without any auth and see what happens.
And it worked, it serves the purpose I am looking for. But I can't help but wonder, why does it work? Everything in documentation suggests that you have to have an auth token or go through oauth. Is this intended functionality that I can rely on for my use case? Am I correct in understanding that maybe having auth in API calls is only needed when you are trying to manipulate data? If it is intended, I think this should be documented since I am pretty sure I am not the only one trying to do this.
Solved! Go to Solution.
Since you're already logged in (or in your case, masquerading as a student), you're authenticated, and your authentication token and other session data (e.g., cookies) are stored in your web browser. When you make an API request, your browser simply uses the existing token to authorize the call
Most actions performed in Canvas are executed via the API—for example, GET
to retrieve course enrolment information, POST
to submit an assignment, or PUT/PATCH
to update a discussion post. The Canvas frontend makes these API calls behind the scenes and visually displays the resulting data, which is why a student can technically make API requests
The Permissions assigned to each role (e.g., Student, Teacher) determine what types of actions users can perform via the API
An Authentication token is required when calling the API from an external system. This token functions like a "username and password"—it authenticates your identity and allows you to make requests on behalf of that user.
Hope this helps. Feel free to let me know if you need any assistance using the API.
Since you're already logged in (or in your case, masquerading as a student), you're authenticated, and your authentication token and other session data (e.g., cookies) are stored in your web browser. When you make an API request, your browser simply uses the existing token to authorize the call
Most actions performed in Canvas are executed via the API—for example, GET
to retrieve course enrolment information, POST
to submit an assignment, or PUT/PATCH
to update a discussion post. The Canvas frontend makes these API calls behind the scenes and visually displays the resulting data, which is why a student can technically make API requests
The Permissions assigned to each role (e.g., Student, Teacher) determine what types of actions users can perform via the API
An Authentication token is required when calling the API from an external system. This token functions like a "username and password"—it authenticates your identity and allows you to make requests on behalf of that user.
Hope this helps. Feel free to let me know if you need any assistance using the API.
Hello Jerry, thanks for the swift help on this! That is what I suspected but couldn't confirm through the docs, or maybe it was in there somewhere and I just didn't find it. But in any case, that is a great distinction of external systems using the API and using the API within Canvas itself with a logged in state being the needed authentication. I could have just run with it regardless, but I feel more comfortable relying on it if I understand why it does what it does.
As @jerry_nguyen wrote, when you are accessing Canvas through a browser, the cookie contains authorization information. Open up the developer tools in your browser and switch to the network tab. Pick a request and you'll see a Cookie in the request headers.
There is a _csrf_token, usually towards the end, which is your authorization token. There will also be one in the cookie response header.
Because that is part of a cookie, the browser sends it with any request from its domain. In fact, you can open a new browser tab, make an API request, and it will send the token with the request will work. Go ahead and try it with something like https://<instance>/api/v1/users/self and you should get JSON about your user account.
That means that you can embed JavaScript (globally with the custom JavaScript under theming or locally using a userscript manager like Tampermonkey) and you can make GET calls to the API from within your code.
As for Canvas not documenting it. It is as reliable as anything custom with Canvas. It works until it doesn't. Don't let that scare you. They are extremely unlikely to change this. They warn you that any of the custom JavaScript you needs to be tested and you have to pay attention to changes and monitor your beta instance to make sure it doesn't break.
That said, Canvas likely won't change the authentication portion. There has been talk of deprecating third-party cookies and some browsers block those by default. This token is within a first-party cookie and your JavaScript will be running within Canvas so it will allowed to access it.
This works for any GET request. If you want to do a PUT or POST, you need to send the _csrf_token with the request. You don't send it as _csrf_token, though, you have to set authenticity_token to the value of the _csrf_token that Canvas sent in the response header. I run it through decodeURIComponent before using it. Again, this is not necessary for a GET request.
When you make an API call from within JavaScript loaded inside Canvas, do not include an authorization header in the request. That would require a regular token that was generated and it would be extremely bad to include that in your JavaScript code that anyone can look at. Let the cookies handle things for you when you're running code from within Canvas. If you're running code outside the browser, then you need a token and authorization header.
While Jerry mentioned that most calls are made through the API, there are some internal, non-API calls, as well. In those instances, the JavaScript that you load through the theme or a userscript will still work. This allowed me to write code to get the access report data for an entire class when a non-API call was the only way to do it. The mobile app didn't have that feature and it never got converted into an API.
If you're looking for publicly documented features, then the API is safer. Those non-documented calls exist, but could change without notice. In the 13 years I've been using Canvas, that rarely happens. Any changes often come as part of an upgrade, such as the Enhanced Rubrics or part of their push to move more things to use Instructure UI and get away from jQuery.
To interact with Panda Bot, our automated chatbot, you need to sign up or log in:
Sign InTo interact with Panda Bot, our automated chatbot, you need to sign up or log in:
Sign In