Help

4.6.13. Disallowed Fields in API Routes

In this chapter, you'll learn about disallowed fields in API routes, how to apply them to custom API routes, and how to apply them to Medusa's API routes.

Note: The disallowed query configuration is available since Medusa v2.18.0.

What are Disallowed Fields?#

An API route can block specific field path segments as a hard security boundary. Medusa removes these fields from the query before it executes, regardless of what the client requests.

Use disallowed fields to guard internal or sensitive relations on a route, such as stock locations, price sets, or a custom link. This prevents a client from pivoting from a public resource into private data.

For example, if a custom API route blocks the campaign segment, a request to GET /store/custom?fields=promotions.campaign.budget returns the data without the campaign relation, even if the client explicitly requests it.

Important: Medusa's own API routes don't set disallowed fields. They restrict what a client can retrieve through their allowed fields instead. A field that isn't in a route's allowed array never reaches the query, so the allowed list is the boundary that protects Medusa's routes.

Disallowed fields are different than allowed fields:

Allowed fields are an opt-in list of the fields a route can retrieve. Medusa applies them to its API routes to keep them performant and secure.
Disallowed fields are a deny list that Medusa always enforces, even if the field is in the allowed list, and even if the client requests it explicitly. Medusa doesn't apply them to its API routes, so you set them on the routes that need them.

How to Disallow Fields in Custom API Routes?#

To block field path segments in a custom API route, pass a disallowed array to the validateAndTransformQuery configuration:

src/api/middlewares.ts
1import {2  validateAndTransformQuery,3  defineMiddlewares,4} from "@medusajs/framework/http"5import { createFindParams } from "@medusajs/medusa/api/utils/validators"6
7export default defineMiddlewares({8  routes: [9    {10      matcher: "/store/custom",11      method: "GET",12      middlewares: [13        validateAndTransformQuery(14          createFindParams(),15          {16            defaults: ["id", "title"],17            isList: true,18            disallowed: ["orders", "customer"],19          }20        ),21      ],22    },23  ],24})

Medusa strips any field path that contains orders or customer as a segment from the query before it executes.

Each entry of the disallowed array is either:

A string, which Medusa matches against a whole field path segment. So, orders also blocks orders.customer.email.
A regular expression, which Medusa tests against each segment, such as /_link$/, and against the full dotted path. This allows you to block a relation at a specific position. For example, /\.orders(?:\.|$)/ blocks orders everywhere but at the root.

Warning: A disallowed array isn't a substitute for an allowed array. A deny list only blocks the segments you thought of, whereas an allowed list blocks everything you didn't list, including relations that you add to the data model later. Set allowed on your custom API routes, and use disallowed to block a segment that the allowed list would otherwise let through.

How to Disallow Fields in Medusa's API Routes?#

Note: Setting disallowed fields on a request is available since Medusa v2.21.0.

Medusa's API routes don't set disallowed fields. If you add a field to a route's allowed list and want to block a segment under it, apply a global middleware that sets the disallowed property of the request object.

For example, to block the payment_collection segment on the List Products Store API Route, create the file src/api/middlewares.ts with the following content:

src/api/middlewares.ts
1import { defineMiddlewares } from "@medusajs/framework/http"2
3export default defineMiddlewares({4  routes: [5    {6      matcher: "/store/products",7      middlewares: [8        (req, res, next) => {9          req.disallowed = ["payment_collection"]10          next()11        },12      ],13    },14  ],15})

Medusa strips any field path that contains payment_collection as a segment, even if the path is in the route's allowed list.

The property replaces the route's configured disallowed fields rather than adding to them. Medusa's API routes configure none, so the array you set is the full deny list for the request. On a custom API route that configures disallowed, include the segments you still want to block:

src/api/middlewares.ts
1req.disallowed = [2  "orders",3  "customer",4  "payment_collection",5]

Important: This approach only works using a global middleware, since Medusa applies the disallowed fields in a route middleware. It also only applies to the request that the middleware handles, so it never leaks into other requests.

Was this chapter helpful?