CORS for TYPO3

Why headless TYPO3 projects fail immediately without a correct CORS configuration

As soon as a TYPO3 system no longer just renders HTML but delivers JSON APIs to JavaScript clients on other domains, the browser hits the Same-Origin Policy. Without explicit Cross-Origin Resource Sharing (CORS) headers, it blocks every fetch call that originates from a different origin than the API itself. For every headless TYPO3 approach, every microservice integration and every setup in which a frontend on app.example.com talks to a backend on cms.example.com, a clean CORS configuration is the basic prerequisite. It does not live in an extension alone but is an interplay of TYPO3 middleware, web server configuration and reverse proxy setup.

Typical use cases

An e-commerce retailer with 40,000 orders per month runs a product catalogue in TYPO3 and a React-based storefront on a separate domain. The storefront queries product data, stock levels and price information through a JSON API implemented as TYPO3 middleware. Without correct CORS headers, the browser blocks every AJAX call with the error message “has been blocked by CORS policy”, and the storefront stays empty. The solution is a middleware that sets Access-Control-Allow-Origin precisely to the known frontend domains and answers preflight OPTIONS requests correctly.

A second case is a company that runs TYPO3 as a content hub for several brand websites. Each brand has its own domain but renders certain modules such as news listings or product images client-side from the central TYPO3 instance. CORS has to be configured so that all brand domains are permitted but foreign domains are not. A dynamic origin check against a whitelist in the TYPO3 site configuration is the right approach, rather than a blanket wildcard.

The third context is scientific consortia that maintain a research database in TYPO3 and offer access to research institutions worldwide through an open API. Here the CORS policy is deliberately open, but it has to be combined with an authentication layer, so that every origin may call the API but only a valid token returns data.

Technical architecture: middleware, PSR-15 and preflight

In TYPO3 v12 and v13, the correct place for CORS headers is a PSR-15 middleware hooked into the request pipeline. It checks the origin header of the incoming request, compares it to a configured whitelist and sets the appropriate Access-Control-Allow-Origin, Access-Control-Allow-Methods and Access-Control-Allow-Headers headers in the response. For POST, PUT or DELETE requests with custom headers, the browser first sends an OPTIONS preflight request that the middleware has to answer without authentication, otherwise the actual request fails.

The configuration can be maintained via the site configuration as a YAML array, alternatively directly in the ext_localconf.php of your own extension. What matters is that credentials handling (cookies, authorisation headers) only works if Access-Control-Allow-Credentials is set to true and Access-Control-Allow-Origin points to a concrete origin, not a wildcard. This combination is CORS standard and a common error source for teams that first test with a wildcard and later try to add credentials on top.

Common problems and solutions

The first problem is duplicate header setting. When TYPO3 sets a header and Apache or Nginx additionally sets the same header in the web server configuration, two values arrive at the browser, which rejects the request as malformed. The solution is to define CORS at exactly one place, either in the TYPO3 middleware or in the web server, and deliberately leave the other empty. For reverse proxies such as Traefik or Cloudflare, a third layer is added that can also manipulate headers.

The second problem is preflight OPTIONS requests. The browser sends an OPTIONS request to check before the actual call whether the method is allowed. TYPO3 middleware that first authenticates and then sets CORS headers rejects the OPTIONS request because it does not carry an authorisation header. The solution is to intercept preflight requests early in the middleware chain and answer them without authentication.

The third topic is the combination of CORS and caching. A reverse proxy such as Varnish caches a response with specific CORS headers, and on the next call from a different origin that origin receives the old headers. The consequence is that legitimate users suddenly see CORS errors because they receive a cached response intended for a different origin. A Vary header on origin fixes the problem but forces the cache to hold multiple variants per resource.

Migration and version compatibility

TYPO3 v11 did not yet offer a clean middleware API for all contexts, so CORS configuration was often handled via hooks or directly in the web server. From v12 onwards, the PSR-15 middleware is the intended path, and the migration path from older installations consists of moving existing header manipulations out of the Apache or Nginx config and into the TYPO3 middleware.

For headless setups in TYPO3 v13 combined with EXT:headless by Macopedia, CORS is an essential building block and is explicitly covered in the extension documentation. Gosign has delivered several such headless projects and, where needed, also coordinates between development teams that own frontend and backend separately, so that CORS rules are clearly documented and synchronised on every deployment change. A wrong rule opens an attack vector in which malicious websites can perform actions on behalf of the logged-in user, which is why a clean whitelist is not a comfort topic but a security requirement.

It should also be noted that CORS is not a substitute for authentication. Many development teams configure generous CORS rules on the assumption that this makes the API secure and forget that every origin the browser permits has the same access as a direct client. Authentication has to happen independently of CORS via tokens, API keys or session cookies, and CORS merely ensures that browsers allow legitimate calls to these authenticated endpoints in the first place. Teams that understand this separation configure their CORS rules much more restrictively and close many unintended gaps.