> 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" ] }, function(){
    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.

## 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" ] }, function(){
    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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.