HTTP Middlewares

HTTP middleware instances are declared under server.http.middlewares and referenced by name from routers.

server:
  http:
    middlewares:
      strip_api:
        strip_prefix:
          prefix: /api
      backend:
        service:
          loadbalancer:
            servers:
              - url: http://localhost:3000
    routers:
      app:
        path: /api/*
        middlewares:
          - strip_api
          - backend

Important Rule

A single named middleware can hold only one middleware type. If you need both headers and a service proxy, define two named middlewares and chain them in the router.

Supported Keys

Key	Purpose
access_log	Structured request/response logging.
add_prefix	Add a path prefix before the next middleware.
auth	PostgreSQL-backed unified IAM/OAuth2 middleware.
basic_auth	HTTP Basic authentication with htpasswd hashes.
block	Block methods or paths.
cors	CORS headers and preflight handling.
decompress	Decompress gzip request bodies.
dns_path	Route to DNS-resolved instances selected from the path.
folder	Serve files and SPA assets from a directory.
forward	Forward proxy for HTTP and CONNECT requests.
grpcui	Browser UI for gRPC services.
gzip	Compress responses.
headers	Set or delete request/response headers.
hello	Return a static or templated response.
iam	Deprecated Badger-backed IAM API/UI and permission store.
iam_check	Check request authorization through an IAM API.
iam_forward_auth	Forward-auth endpoint for external proxies.
info	Return cookie or session value content.
inject	Rewrite response bodies by path.
log	Lightweight request log line.
login	Login UI and OAuth2 code/password flows backed by session.
oauth2	Deprecated OAuth2/OIDC-compatible endpoints backed by IAM.
oauth2_resource	Protect an upstream (e.g. an MCP server) as an OAuth2 resource server (RFC 9728).
path	Replace the request path and optionally set request headers.
print	Print POST bodies to stderr for debugging.
rate_limit	Limit requests by all traffic, IP, or real IP.
redirect_continue	Redirect when a regex rewrite changes the URL, otherwise continue.
redirection	Always redirect.
regex_path	Rewrite the URL path with a regex.
request	Make an outbound HTTP request and return its response.
request_id	Ensure X-Request-Id exists.
role	Check roles in parsed claims.
role_check	Path/method role authorization after session.
role_data	Return data based on roles in parsed claims.
scope	Check scopes in parsed claims.
service	Reverse proxy and load balancer.
session	Validate bearer/session tokens and set identity headers.
session_info	Return selected claims from a session token.
set	Set Turna request-context values for other middlewares.
splitter	Select a sub-chain using expressions.
strip_prefix	Remove one of several path prefixes.
template	Render a response body template.
token_pass	Generate a JWT and redirect or call another service.
try	Retry a chain with a rewritten path for selected response statuses.
url	Modify scheme, host, path, query, fragment, and port by rule.
view	Serve a combined Swagger/API documentation UI.