Child Item

Modernizing Our Files API for Enhanced Security and Performance

We're excited to announce important updates to our Files API, designed to bring you a more secure and efficient experience when working with your files. These changes reflect our commitment to following current best practices and providing you with the most robust tools possible.

Previous Change: File UUIDs Transitioned Out of Files API Responses

As previously communicated, File UUIDs are no longer included in Files API responses. While removed from the API, we want to assure you that they remain available in Canvas CD2 if needed. This API change was necessary as part of our effort to modernize our API and enable improved security and access control.

Important Update: Authenticated File Downloads

We are making a crucial change to how files are downloaded which will enhance security and provide more granular control over file access. Moving forward, when downloading files, you will continue to use the download URL returned by the Files API response. However, it is now essential that your authentication token (used in Authorization header) is in use for all file downloads.

What's Changing and Why:

Currently, download URLs may include a "verifier" parameter, which allows access without a token. The current plan is that in the March 25, 2026 Canvas Deploy, this "verifier" parameter will be removed from the download URL, preventing access without your authentication token.

Why is this important? Utilizing authentication tokens enables more robust permission control for file access, ensuring that only authorized users can download your files. This greatly enhances the security of your data.

Action Required:

Authenticated downloads are live in Canvas Beta and Prod, and we strongly encourage you to update any existing scripts immediately to ensure your authentication token is in use for all file downloads. By making this update now, you'll ensure a seamless transition and maintain uninterrupted access to your files.

We believe these updates will significantly improve the security and performance of our Files API, and we appreciate your cooperation in adapting to these changes. If you have any questions, please don't hesitate to reach out to our support team.

Find more posts tagged with

Canvas LMS

Comments

Chris

Hi @jperkins,

Thanks for the info. I have a few questions around this that perhaps others may have too…

First, could you provide some specific dates for the changes above? When will authenticated downloads be available in prod? When will verifiers be removed from links? I know you may not want to be nailed down to specific dates yet, but as an admin the dates are a necessity for planning purposes

Second, will there be a report (perhaps similar to the one created to help identify API calls without a user agent) created for this? It would be great to see some kind of report of things doing unauthenticated file downloads so we can ensure everything is updated.

Third, When you say "ensure your authentication token is in use for all file downloads", are you referring to our API token, which I typically have in the header as '"Authorization': f'Bearer {api_token}'" in my python code? If not, can you explain what kind of auth is necessary?

Finally, can you confirm a way to test this? In beta, should we remove the verifier part of a link, add the Auth as described above, and just ensure the file download works?

Look forward to your thoughts on all of this!

-Chris

James

@Chris

It works now in production. If I take a file link for a submission that has a verifier on it and remove the verifier= parameter, I get a request to login through our SSO. If I leave off the verifier parameter but add the token Authorization: Bearer token to the header, then it returns a 200 status code.

Let's say that the file returned is "<instance>/files/312427528/download?download_frd=1&verifier=<redacted>"

Technically, it gives me a series or redirects.

If I leave off the query string completely and just send "<instance>/files/312427528/download", then I get three redirects.

The first is to a file to a file in canvas-user-content.com. It includes the download_frd=1 and an sf_verifier parameter, which is a JWT token. If you try to access this directly without an authorization token, it fails with unauthorized. If I try including the authorization header, then I got a 400 bad request. I will note that the request returned a cookie with a canvas_session and csrf token, but I didn't try using those to access it.
The second redirect is to a file on inscloudgate.net. This included query parameter of download=1 and a JWT token. When I tried to access it directly, it told me the JWT was rejected because the JTI has already been used.
The third redirect was also on inscludegate.net and including a JWT token but no cookies and no csrf token. It actually delivered the binary contents of the file I was trying to download.

When I ran it again to test whether the ?download_frd=1 helped, it gave me the same three redirects.

I tried it again including the verifier= and authorization header (this would have failed in the past) and it worked.

It also still works with the verifier= but without the authorization header. This is good as it would be essentially no warning before a breaking change if it didn't work.

Basically, it seems that you can immediately (as Jeremy said) start adding the Authorization: Bearer <token> header, enable redirects in the request, and get it to work.

I cannot say when the verifier parameter will stop working.

As for a report, you might have to use the web logs from CD2 to look for requests with a verifier in the url. But it's going to be impossible to know which ones are sending the authorization header because that's not logged and it should be none for right now. But that might give you a place to start. You could modify your scripts to remove the verifier search parameter if you're including your authorization header in an attempt to whittle down which ones are still using it. That may be more work than you want to go through. Ultimately, it may be a case of not knowing everywhere it's used until it's not working anymore.

Chris

Thanks, @James.

I did do some quick coding changes and tests when I first saw this post today. I didn't realize these changes may be live in prod, as the post just called out the Beta environment. I did what I mentioned in my post (started including the bearer token and removing the verifier querystring from some of the file downloads (report CSVs) my script does, and it ran in beta without issue (the python requests library must handle the redirects internally, which is great for me). I just wanted to make sure that was the intended method for testing.

I really want to try to be proactive so nothing breaks whenever the verifier stuff is actually removed by Instructure at some point, but maybe we're just going to have to check as much s we can and prepare to look for any remaining failures at that point.

-Chris

jperkins

@Chris We anticipate enforcing the change on or around the March 25, 2026 Canvas deploy. We can look into a report, but the authorization headers are discarded before making it to our logs (for security purposes) which makes it quite a bit tougher to generate than what we did for user-agent. As far as testing, you can certainly remove the verifier, but really it's about ensuring that when your scripts follow a download url, that you are still providing your authorization header in the download request.

We'll flip the disable verifier flag in beta sometime before the production deploy but have some database migrations and similar to run before we do so. We'll ensure that notice is given for you to test when this is completed.

Thanks for your questions, I've modified the blog post slightly for clarification.

jonespm

I was testing this change in beta and it's not working if you pass a "Enforce Scopes" OAuth token from an API key as a header to download the file, it gives a 401 error. There doesn't appear to be any scopes that are associated with the plain /files/ path. Since there's a verifier parameter right now it does in beta if you don't pass an Authorization header at all and just use the url with verifier from /api/v1/files/:id

I hope that Instructure dev team has a way to allow this to work this before removing the verifier. We require tokens to be scoped and it would break functionality without having something working.

Ideas that might work that I can think of are:

Rely on a different existing scope (like /api/v1/files/:id) for access control
Include a new scope specific for file downloads (currently nothing like this exists)
Have a new API (like /api/v1/files/:id/download) and a new scope for that API to allow for downloads.

Thanks!

Child Item