> For the complete documentation index, see [llms.txt](https://coldbox.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coldbox.ortusbooks.com/the-basics/routing/routing-dsl/middleware-groups.md).

# Middleware Groups & Exclusions

Register reusable, named middleware bundles and opt individual routes out of middleware they'd otherwise inherit.

Once you're attaching the same [middleware](/the-basics/routing/routing-dsl/middleware.md) list to more than one route or group, naming it once beats repeating it everywhere.

## Registering a Named Group

`middlewareGroup( name, [ ...targets ] )` registers a reusable bundle. Reference it by name from `.middleware()` or a group's `middleware` option, exactly like any other target:

```javascript
middlewareGroup( "api", [ "RequireApiKey", "RateLimiter" ] );

route( "/orders" ).middleware( "api" ).toHandler( "orders" );

group( { pattern : "/api", middleware : [ "api" ] }, () => {
    route( "/users" ).toHandler( "users" );
} );
```

{% hint style="danger" %}
**Register the group before referencing it.** Expansion happens immediately, at registration time - a name referenced before its `middlewareGroup()` call is silently treated as a literal target (e.g. a WireBox ID) instead of being expanded. Declare your groups at the top of `configure()`.
{% endhint %}

Groups are flat - a member can't itself be the name of another group. Each entry is a concrete closure, WireBox ID, or object.

{% hint style="success" %}
To name just one closure, lambda, or WireBox ID, use [`registerMiddleware()`](/the-basics/routing/routing-dsl/middleware.md#registering-named-middleware). It shares this namespace, so a name cannot be both a group and registered middleware unless you pass `force = true`.
{% endhint %}

## Excluding Inherited Middleware

`withoutMiddleware()` opts a single route out of middleware it would otherwise inherit - from an enclosing group, or from its own earlier `.middleware()` calls.

```javascript
group( { pattern : "/api", middleware : [ "api" ] }, () => {
    route( "/users" ).toHandler( "users" );                              // runs "api"
    route( "/health" ).withoutMiddleware( "api" ).toHandler( "health" ); // opts out
} );
```

Match by the same name used to attach the middleware:

* **A WireBox ID** - excludes that one target
* **A `middlewareGroup()` name** - excludes every member that group expanded to, not just a same-named single target
* **`"*"`** - strips everything for that route, inherited or its own

```javascript
route( "/public" )
    .middleware( "RateLimiter" )
    .withoutMiddleware( "*" )
    .toHandler( "public" );
```

{% hint style="info" %}
Closures and object instances have no name to match, so they can only be kept off a route by not attaching them in the first place.
{% endhint %}

Call order doesn't matter - `withoutMiddleware()` and `.middleware()` can appear anywhere in the fluent chain and the exclusion is still applied once the route finishes registering.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://coldbox.ortusbooks.com/the-basics/routing/routing-dsl/middleware-groups.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.