Astro CORS for Magento 2 — Secure Cross-Origin GraphQL for Headless
Astro CORS is the cross-origin layer a headless Magento 2 store needs. It applies a configurable CORS policy to GraphQL and REST — your allowed origins, methods and headers — handles preflight OPTIONS requests correctly, and adds the CORS headers to actual responses, not just the preflight. I…
Going headless? The browser will block you before you ship a single page
The moment your Astro storefront calls Magento's GraphQL from a different domain, the browser's same-origin policy steps in — and unless the backend answers preflight requests and returns the right CORS headers, every request fails with a console error that has nothing to do with your code. Magento doesn't ship a CORS layer. Astro CORS adds one: a policy you control over GraphQL and REST, correct preflight handling, and a clean way to retire the old Luma storefront, so the decoupled build just works.
What you'll use it for
- Connect Astro to Magento — let a storefront on its own domain call GraphQL and REST without the browser blocking it.
- Support multiple environments — allow
localhostfor development and your live domains for production from one list. - Tidy up the backend — 301-redirect any leaked Luma URL to the matching page on your headless frontend, good for SEO.
- Keep callbacks alive — exempt OAuth and payment-return paths so they keep working on the backend host.
How it works
Secure by default, not wide open
A CORS layer is only useful if it's also safe. You name the exact origins your storefronts run on, rather than leaving the door open — and when a wildcard is used, credentials are handled correctly so the policy never quietly becomes insecure. The redirect that retires the old Luma storefront only touches browseable pages: GraphQL, REST, the admin and your /media and /static assets are never redirected, and you keep an allow-list of front names (like OAuth callbacks and payment returns) that must continue to work on the backend host.
Specifications
| CORS scope | GraphQL and REST, with configurable allowed origins, methods and headers |
|---|---|
| Preflight | Correct handling of OPTIONS preflight requests |
| Responses | CORS headers applied to actual API responses, not only preflight |
| Wildcard safety | Credentials handled correctly when a wildcard origin is used |
| Headless redirect | Optional 301/302 redirect of Luma storefront pages to your frontend |
| Exemptions | Allow-list of front names kept on the backend (OAuth callbacks, payment returns); APIs, admin and assets never redirected |
| Delivery & licence | Composer install, per-domain licence key, updates via Composer |
Works with
Part of the AgenticEcom suite for Headless & Astro:
Foundational for any headless build; pairs with Astro ISR for cache freshness. Included in the Enterprise bundle and the Astro frontend licences.
Frequently asked questions
Why do I need a CORS module for headless Magento?
When your storefront runs on a different domain from Magento, the browser blocks cross-origin API calls unless the backend answers preflight requests and returns the right CORS headers. Magento has no built-in CORS layer, so those calls fail until you add one.
Can I restrict which sites can call my API?
Yes. You list the exact origins allowed to call GraphQL and REST, along with the permitted methods and headers. A wildcard is available for development, with credentials handled safely.
What is the Luma-to-frontend redirect for?
After going headless, the Magento backend still serves its old storefront pages. The optional redirect sends those URLs to the matching page on your Astro frontend — without ever redirecting GraphQL, REST, the admin or your media and static assets.
Will it break my OAuth or payment callbacks?
No. You keep an allow-list of front names that must stay on the backend, such as social-login and payment-return URLs, so those continue to work even with the redirect enabled.
Which Magento and PHP versions are supported?
Magento Open Source 2.4.9 and later 2.4.x, verified on PHP 8.4 and 8.5.