Headless Lock

When you run a headless Magento behind an Astro (or other) storefront, the old Luma frontend is still alive underneath — every product, category, checkout and CMS page still responds. That’s duplicate content for Google, a confusing second checkout, and a surface you don’t want exposed. Headless Lock turns the Luma storefront off with a single toggle — while GraphQL, REST and the Admin keep working untouched, and payment and OAuth callbacks keep flowing.

Install

Install Headless Lock with Composer using your AgenticEcom licence key (find it on your My Licences page — one key unlocks every module you own):

# 1. Register the AgenticEcom repository (once per store)
composer config repositories.agenticecom composer https://repo.agenticecom.net
composer config --global --auth http-basic.repo.agenticecom.net <YOUR-LICENCE-KEY> x

# 2. Require this module
composer require agenticecom/module-headless-lock

# 3. Apply it
php bin/magento setup:upgrade && php bin/magento setup:di:compile && php bin/magento cache:flush

Have the whole platform?

Install every module in one command with composer require agenticecom/suite — see Install the complete suite.

It ships switched off

Installing the module changes nothing on its own — it ships disabled and domain-neutral, so it can never silently lock a store on deploy. You turn it on deliberately, per store view.

Compatibility

Magento

Open Source 2.4.9 GA (and later 2.4.x).

PHP

Tested on 8.4 and 8.5.

Scope

Per store view — lock one store, leave another open.

Bypass-proof

Blocks at the front controller, before routing.

What it blocks — and what it never touches

Blocked (when on)

Every native frontend page: catalog (products, categories, search), CMS pages, checkout, the customer account, 404s and any unknown frontend route.

Always allowed

GraphQL (/graphql), REST (/rest) and the Admin (/admin) run in their own areas and are never affected — plus every payment gateway and OAuth/social-login callback.

You decide

Any extra frontend route on your install (a non-standard payment module, /llmstxt, a custom webhook) can be allow-listed.

Payment & OAuth callbacks are automatic

Routes for Stripe, PayPal, Braintree, Adobe Payment Services, the vault, /oauth, social login and Xero are hard-coded as always-allowed — you do not need to tick them. So enabling the lock never breaks a checkout return or a sign-in callback.

Turn it on

1. Go to Stores → Configuration → AgenticEcom · Headless & Astro → Headless Lock → Frontend Lockdown. (Pick the store view first if you only want to lock one.)

2. Set Block Luma Storefront to Yes.

3. Choose When Blocked:

   • Redirect to URL (302) — send shoppers to your headless storefront. Reversible, so caches can be lifted later.
   • Return 410 Gone — tell search engines the Luma page is permanently gone (it gets de-indexed).

4. If you chose redirect, set the Redirect URL to your storefront (e.g. https://yourstore.com). If it’s left blank, a 410 Gone is returned instead.

5. Save Config. The Luma storefront is now dark; your APIs, Admin and payment callbacks keep working.

Allow an extra route or path

Most stores never need this — payment and OAuth are already covered. Use it only for a non-standard integration.

A registered route

Allowed Frontend Routes lists every frontend route registered on your install (with its module name). Tick any extra one you need to stay reachable while the lock is on — for example a non-standard payment module, or /llmstxt for the AI-crawler file.

A raw path prefix

Additional Path Prefixes (advanced) takes one path per line (or comma-separated) for callbacks that aren’t a standard route front-name. A request is allowed if its path equals or starts with a listed prefix — e.g. /webhook/my-service.

FAQ

Will enabling this break my GraphQL or REST API?

No. The block is frontend-area only. GraphQL (/graphql) and REST (/rest) run in separate areas and the blocking plugin isn’t even loaded there, so they’re never affected. The Admin is likewise untouched.

What about Stripe / PayPal checkout return URLs?

They’re automatically allowed. The payment-gateway routes (Stripe, PayPal, Braintree, Adobe Payment Services, the vault) and OAuth/social-login are hard-coded as always-allowed and can’t be blocked, even if you don’t tick them in config.

My custom payment module’s callback is blocked — why?

The lock only auto-allows the standard gateways. If your module registers a frontend route it appears in Allowed Frontend Routes — tick it. If its callback isn’t a registered route, add its path to Additional Path Prefixes (advanced).

302 redirect or 410 Gone — which should I pick?

Use 302 redirect while you’re transitioning, so you can point shoppers at the new storefront and still reverse it. Use 410 Gone once you’re certain the Luma frontend is retired for good — it tells search engines to drop those URLs.

Can I lock one website but not another?

Yes. Every setting is store-view scoped. Select a store view at the top of the Configuration page, enable the lock there, then leave the other store views disabled. Verified clean on Magento 2.4.9, PHP 8.4 and 8.5.