Enforcing User-Agent Header for Canvas API Requests

[SarahCornelius]

Introducing Stronger API Governance in Canvas

Data privacy and security is more important than ever before. We’re deeply committed to protecting the data of our institution users AND our partners–that’s why we're excited to share several improvements to our API security and monitoring framework. 

For integration partners, the key update is that beginning October 1, our Beta environment will reject any HTTP requests that do not include a User-Agent header. This change will be deployed to our Production environment on January 17, 2026.

This enforces a best practice across our platform and throughout the software industry aligning with our broader goals for API governance, observability, and security.

 

Why This Matters to You

Enhanced Security
Requests lacking a User-Agent often come from automation or misconfigured scripts—and can signal scraping or other unwanted behaviors. Blocking these helps reduce our threat surface and better protects the platform.

Improved Observability & Governance
A valid User-Agent is crucial for attributing requests to their source. This enables better audit trails, usage insights, and accountability—essential elements of a robust API governance model.

Operational Efficiency
Having clean, traceable API traffic allows for faster debugging, usage pattern analysis, and resource allocation. It helps us support teams more effectively while maintaining system reliability.

 

How This Affects You

• Automated tools, scripts, or cron jobs that don’t explicitly set a User-Agent will begin failing with a 403 error code.
  
  
• Standard browsers and many HTTP clients already include a User-Agent—so most normal interactions remain unaffected.

 

What You Should Do Next

 

Language Specific Examples

 

Additional Updates to User Access Tokens

Beyond enforcing the User-Agent header, we’re also making several changes for Canvas Admins to help ensure efficient and appropriate management of API access. These updates are planned for early Q4 and include:

• Requiring that all user access tokens have a purpose listed
• Requiring that all user access tokens for users with only student roles have an expiration date not more than 120 days from the date of creation
• Enabling administrators to prevent users with only student roles from creating user access tokens
• Enabling administrators to more easily view and remove user access tokens

[chriscas]

@SarahCornelius,

Thank you for the info, and for giving all of us 3 months to adapt to this change.

This is definitely a big change in terms of the scope, even if the code changes themselves should be relatively simple.  I'm wondering If Instructure may be able to provide a report of calls rejected for the missing user agent after Jan 1.  I'm fairly sure I know everything we do internally with the API, but there could definitely be something I'm forgetting and we'd also like to know if any vendor calls to our instance start failing.  We're also not a huge campus, so this may be an even bigger concern for places with much more API usage.

-Chris

[IanGoh]

Would this also affect calls to Canvas Data 2 (CD2)?

[IanGoh]

Hmm, AFAIK it still is not enforcing the User-Agent header in BETA as of 10/02.  Did they delay the push to BETA?

[jwals]

I can also still successfully make API calls to beta with a blank UA string specified as of 10/02.

[AlexSlaughter]

@chriscas We're happy to provide a report scoped to a specific domain both before and after Jan 1 to help make this transition as seamless as possible.

@IanGoh this change will not affect CD2. This change is specifically scoped to Canvas domains.

@IanGoh // @jwals - The change is currently being deployed on a percentage basis (as we do with many infrastructure changes) to Beta. It's expected to reach 100% by Tuesday (10/7). 

[IanGoh]

Confirmed we're now getting 403s in BETA if we don't have the User-Agent header. @AlexSlaughter do you know when TEST will be impacted?

[gemma_sinclair]

Has this change already been applied to Test with no warning? 

[IanGoh]

😢 I confirm we also see it in our TEST environment.   

Ian

[JeffMcDonald]

This also hit us in test before it landed in beta.

[jwals]

This change arrived in our test instance as well. It's also a little odd/inconsistent that lacking a UA string returns an HTML page, while using an invalid token returns a JSON response like all other API calls.

[Robert_Stefanek]

Hey all. Just so you know, this caused a major project on our end to completely ground to a halt because we were building something out in test before we launched it in prod. While we appreciate the advanced notice that this was going to hit prod on Jan 1, we really needed advanced notice that it was hitting test.

[AlexSlaughter]

@IanGoh yes, beta and test were updated at the same time.

@gemma_sinclair Test and Beta are both considered lower environments to production so they receive updates before production as the 90 day change notice policy applies to production.

@jwals Great callout. You're seeing different levels of enforcement with different toolchains available. The UA check is performed at the edge where nothing is known about the type of response expected hence a generic response.

@Robert_Stefanek thanks for the feedback. We are having conversations internally about the expectations around environments lower than production so we can make future changes smoother.

[chriscas]

Hi @AlexSlaughter,

Thanks for being willing to provide a report on this at some point, we may take you up on that offer in the future when the deadline is closer.

Regarding the text environment, I definitely didn't expect this change to be included there before the production deadline.  As far as I know as a Canvas Admin, it's always been the practice that the test environment is running almost the same code as production.  The What is the Canvas test environment? - Instructure Community - 262267 guide even calls out that test is updated with prod changes on the Monday after a prod release.  I feel like this change should be reverted from the test environment until January, but definitely leave it in Beta.

-Chris

[RickBargerhuff]

Hello everyone! Like @Robert_Stefanek , we have multiple development instances that reference beta. These instances are owned by different developers of the development team I am a part of. This change prevented all current dev instances from communicating with Canvas.

@AlexSlaughterRegarding " The UA check is performed at the edge where nothing is known about the type of response expected hence a generic response.":

In the future, JSON output should be provided with the enforcement warning encapsulated as a request error the way API errors are documented. For example:

[
  {
    "message": "You are not authorized to access this site because you have not provided a valid user agent. For more information, please see the API Announcement at https://community.canvaslms.com/t5/Canvas-LMS-Blog/Enforcing-User-Agent-Header-for-Canvas-API-Requests/ba-p/658205"
  }
]

 For anyone interested, these are the User-Agent strings for Google Chrome across all 3 browsers and cURL.

Linux: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36

Windows: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36

Mac OS X: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36

cURL: curl/8.14.1
Note: cURL User-Agent is formatted using the following:

$curl_info = curl_version();
$userAgent = 'curl/' . $curl_info['version'];

[AlexSlaughter]

Hi @chriscas, I definitely appreciate what you're saying and thank you for the details on how Test looks from the customer protective. Very valuable.

I think further clarification on Test environments is needed as that post states that "The test environment inherits new and updated features" and  this is not a feature, but rather a policy change which is materially different to us but looks similar at the end of the road to customers. It is a nuance thing, but given how complex Canvas is, nuance is important.

We're working internally on updating our messaging too in order to better emphasize what is a bit understated in that post which it is not subject to the standard SLA/SLO as production which the change notice falls under.

To your earlier comment about the report, we are happy to run reports for test and beta to show what dev keys and access key are making agentless request to help facilitate the identification and remediation of errors that have a occurred as a result of this change.

If there is any additional telemetry that is needed to aid in getting ready for Jan 1, we are extremely open to providing those details to Canvas Admins.

-Alex

[Robert_Stefanek]

I would like to second @chriscas's suggestion that this change be reverted from the test environment until January. Could I add to it that the message that @RickBargerhuff quotes above, which is currently returned with an unauthorized call, is instead returned with successful requests to any environment (prod, beta, test) so that additional users have the opportunity to learn about this change before it hits?

[gemma_sinclair]

@AlexSlaughter you don't seem to be appreciating the immediate and direct impact this change has had on your customers - and a blog post does not constitute effective communication about platform breaking changes - even if they are on a non-production environment.

As above this change needs to be reverted from Test immediately as it is preventing institutions from their regular testing and release processes.

I suggest delaying this change until 1st December in Test environment to allow institutions enough time to make the changes to their tools and then validate in Test before the changes are released to Production on 1st January 2026.

Will the Instructure engineering team be available on 1st January 2026 in case issues arise on Production that were not found in Test/Beta?

[AlexSlaughter]

Hi @RickBargerhuff we did look into either doing a route prefix on `/api` or looking at the `accept` header, and determining what type of response to return. Unfortunately  in our testing we found many examples where both assumptions broke down and became more confusing than constructive. I appreciate the thoughts around how to make the experience better though!

Also, hello @Robert_Stefanek! I'm not quite sure I understand what you're asking. This message only appears as the body response if UA is not present on beta and test environments. Mutating successful responses to contain a payload about a warning that doesn't apply to the request that was made would break a great deal number of things. Would you mind clarifying "successful requests to any environment"? We are preparing to email Canvas Admins that has agentless requests in their prod environment with a list of users and dev keys making requests without an agent to help facilitate knowledge and information around the change and its effects.

[Robert_Stefanek]

Thanks for the response, @AlexSlaughter. I'm not as versed in this as some so I wasn't sure if it would be possible to return a message with a successful response. I just share @gemma_sinclair's concern with increasing the timeline and improving communication.

And to be fair, a great number of things have already been broken by this change. 😉

[AlexSlaughter]

Thank you all for your feedback. We have rolled back Test and we'll have more communications to follow. Please reach out to support if more help is needed.

[sgergely]

@IanGoh 

Would this also affect calls to Canvas Data 2 (CD2)?

No, not yet, the current scope is for Canvas API only.

[IanGoh]

Thanks for the rollback. Confirmed in TEST, we don't require User-Agent again.

[HowieStacy]

Is this being rolled back to all accounts, or just select ones? 

We are brand new to Canvas and were still working in Beta and Test as we prepare to launch Production. 

[AlexSlaughter]

@HowieStacy this change is an environment level change and not an account level change. URLs that have <tenant>.beta.instructure.com will see User Agent enforcement, URLs that have <tenant>.test.instructure.com will no longer see User Agent enforcement as of 10/7/2025 @ 6pm PDT.

[Choachy]

@AlexSlaughter  At the time of this post, has this been rolled back in BETA as well? Or should it be giving a 403 error? I just ran 2 tests against our beta environment, intentionally leaving out the user-agent header, and I'm getting a valid response or 200 status. I'm no expert at this so maybe I'm missing something.

Edit: I can add that my tests were just simple scripts. One a python script and another powershell script. 

For example: 

import requests

API_URL = "https://xxxxxx.beta.instructure.com/api/v1/accounts"
TOKEN = "my_token_here"

headers = {
    "Authorization": f"Bearer {TOKEN}"
    # intentionally no "User-Agent" header
}

response = requests.get(API_URL, headers=headers)

print(response.status_code)
print(response.text)

[sage_freeman]

@AlexSlaughter 

I would suggest Instructure proactively provide all clients "reports for test and beta to show what dev keys and access key are making agentless request to help facilitate the identification and remediation of errors that have a occurred as a result of this change.".

Can I submit a support case to get these reports for our college?

[melodyc_lam]

@Choachy The Python Requests module sends a user agent string automatically in the format "python-requests/{version}" (Source code) which is why you're not seeing any issues.  I would recommend as best practice that you create your own custom agent string anyway for the reasons above that @AlexSlaughter provided.

Also, I would second @sage_freeman's suggestion of getting a proactive report of what is currently being used on our instance so we can proactively fix those scripts or notify those users.

[kfullman1]

Is there a new date for the enforcement of this change in Test? Also, someone should edit the blog post to mention the Test environment.

[dbrace]

@SarahCornelius / @AlexSlaughter / @sgergely,

Besides subscribing to many different areas of the Instructure Community for tracking changes, what can be done to communicate changes like this?

I ask because I only came across this information because @chriscas replied to a question (https://community.canvaslms.com/t5/Canvas-Question-Forum/Beta-API-returns-403-Error/td-p/659278) and referred to this post.

-Doug

[gemma_sinclair]

Agree @dbrace we need advance warning about platform breaking changes - including API changes that affect our tools. Changes like this need to be communicated via the Deploy or Release Notes at a minimum.

[dbrace]

That is right, @gemma_sinclair. 

I did find it at https://community.canvaslms.com/t5/Releases/Upcoming-Canvas-Changes/ta-p/254349 (which redirects to https://community.canvaslms.com/t5/Canvas-Releases/Instructure-Enforcements-Deprecations-and-Breakin... and https://community.canvaslms.com/t5/Canvas-Change-Log/Canvas-Platform-Breaking-Changes/ta-p/262015.

Still, it is buried deep and should be in an area that gets more views like the Releases/Deploys area (https://community.canvaslms.com/t5/Canvas-Releases/tkb-p/canvas-release); even if mentioned that it is something happening in the future.

-Doug

[TrinaAltman]

@dbrace agreed!

All and @AlexSlaughter, also note the date change (now 1/17/26 for prod), which has not been communicated to my knowledge other than places like the API and CLI Change Log and Canvas Platform Breaking Changes page (which also incorrectly list the year as 2025). Above, this very page about the change that we are commenting on still has this listed: "This change will be deployed to our Production environment on January 1, 2026."

Regarding the new date: While I can appreciate moving it away from a holiday, for us the new date falls on a Saturday in front of a holiday weekend that is the start of our spring term. I am concerned about what a rocky start this might result in for us and/or other schools who might not have caught and therefore been able to fix everything that is affected (and particularly for those who aren't even aware that this is coming).

[sage_freeman]

Hi all, I contacted Canvas Support about this change and they provided the following response:

“We have an open engineering ticket to add a warning to the Developer keys page indicating this user agent enforcement change. This engineering ticket also includes work to add a default report to the account reports page "Missing user agents report". If all testing goes as planned this feature should be released by 2025-11-05.”

[chriscas]

Hi @sage_freeman,

Yep, I saw both of those things mentioned in the Canvas Deploy Notes (2025-11-05), so we should see them in production shortly!

-Chris

[IanGoh]

Hope we see the report in BETA first 😉 

[AlexSlaughter]

Hi All,

Sorry for the delayed response.

@dbrace totally agree this needs better consolidation & communication. I have raised internally.

@TrinaAltman - thanks for the flag, we'll get all of our I's dotted and T's crossed.

@chriscas - yes, this should be available in beta now!

We really appreciate everyone's feedback and continued engagement on this topic. Thanks so much!

-Alex

[SarahBlanton]

I just ran the report in our Beta instance and got a file with column headers but no data. I'm guessing this is because there have been no API calls (or calls without User Agent string) to Beta since the report was made available? I would love to have a look at some actual data! 

[IanGoh]

Same as Sarah.  Even though I staged some API 'errors' in BETA, they aren't appearing in the report.  Might have to wait to next week -or- we have to wait for the report to appear in production...

[IanGoh]

After this weekend's BETA refresh, I'm still getting zero results in the Requests Without User Agent report. I even staged a request in BETA yesterday that would not have a User Agent.  Feels like we have to wait for this report to go to PROD....

[IanGoh]

Yay, the Requests Without User Agent report works in production. 🎉

Now, follow up, we're seeing one entry about "LTI 1.1 Grade Passback" - its separate from Developer Keys and/or User-Generated Tokens.  Googling says it's a deprecated LTI.  But apparently it's still something making requests in the last seven days.  What do you suggest in terms of tracking it down on our instance? 

[llettie]

When will this change be applied to the Test environment? We need it implemented prior to the production migration, as our Test instance is where all integrations must be validated before being promoted to production. Thank you.

[gpillsbury]

Has this already been turned on for Prod?  We use Panopto for video storage, and that tool was listed in the report as not having a User Agent.  Today, none of our Panopto videos will display, saying "sso.canvaslms.com refused to connect."

It's not supposed to be enforced in Prod until Jan. 17, 2026 according to this website.  Did something change or could this just be coincidence?

Who is responsible for making sure Panopto works after Jan. 17?  Me as Canvas admin?  Or Panopto?

[coreymead]

Hey @AlexSlaughter , I am an engineer looking to implement this change for our LTI tool. When I tested a few weeks ago I saw the expected error in the beta instance. Today, it seems beta is letting my requests without the User-Agent header through - is there a way for me to tell whether or not the new requirement is available? Just want to make sure that the change we're making is functioning as expected.

Thanks!

[HugoLebegue]

Hi Team, 

I think allowing an arbitrary user agent string doesn't add much value and defies the original intent of the enhancement. 

In other API based SAS, the client is required to add a contact email for best practices, similar to : 

 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36 mailto:xxx@yyy.com'

Since we will all be adding this header, we might think of how to make it consistent, just something to think about.

[schmittda]

I ran the "Requests Without User Agent" on prod and beta and both generated the following errors:
Prod: (Failed, the report failed to generate a file. Please try again.)
Beta: (Failed, please report the following error code to your system administrator: ErrorReport:118300000015427665;)
From the other community comments I've seen, if the report doesn't find requests without a user agent, a report is generated with headings but no detail. Is that still the case or has something changed?
Additionally, all of our API requests require a user bearer token. Does that satisfy the user agent condition?

[IanGoh]

@schmittda "Additionally, all of our API requests require a user bearer token. Does that satisfy the user agent condition?"

No. You need a User-Agent in your header. E.g.,

User-Agent: PostmanRuntime/7.49.1

Ian

[dtod]

Has someone told Zoom?

[dtod]

The vendors are responsible, i.e. Zoom, Panopto, CompTIA.

I'm concerned about the LTI 1.1 Grade Passback, because there are no details there and we have 56,000+ in the past 7 days.

[IanGoh]

Re: LTI Grade Passback - just heard "This appears to be a bug. We're deploying a hotfix that is anticipated to resolve this. The fix will ensure the report includes the Tool ID for all grade passbacks, assigning a unique ID to every line."

[dtod]

Yep. Me too. Gave our CSM an earful today. Given the time of year with holidays and the semester start in January, it's a bit shocking and deeply concerning that our vendors aren't aware of this change.