Skip to main content

Query Parameter Manipulation

The Query Parameter middleware allows you to manipulate query parameters in HTTP requests before they reach your services.

The middleware supports four types of operations: set, append, remove, and rename. Each middleware instance can perform only one operation type, allowing you to chain multiple Query Parameter middlewares for complex transformations.

For detailed configuration options, see the Query Parameter middleware reference.

Common Examples​

API Key Management​

Extract API keys from request headers and add them as query parameters for backends that expect them in the URL:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: api-key-manager
spec:
  plugin:
    queryParam:
      set:
        - name: api_key
          fromHeader: X-API-Key

This example extracts the API key from the X-API-Key header and adds it as a query parameter.

Debug Parameter Removal​

Clean up requests by removing debug-related parameters before they reach production services:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: debug-cleaner
spec:
  plugin:
    queryParam:
      remove:
        - name: debug
        - name: trace
        - name: internal_flag

This example removes debug-related query parameters before forwarding the request.

Legacy Parameter Support​

Maintain backward compatibility by renaming legacy parameters to their modern equivalents:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: legacy-support
spec:
  plugin:
    queryParam:
      rename:
        - from: old_filter
          to: filter
        - from: legacy_sort
          to: sort

This example renames legacy query parameters to their modern equivalents.

JWT Claims to Query Parameters​

Chain the Query Parameter middleware with JWT authentication to extract user context from tokens and pass it as query parameters:

Extracts claims as headers
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: jwt-auth
spec:
  plugin:
    jwt:
      signingSecret: "urn:k8s:secret:jwt:signingSecret"
      forwardHeaders:
        User-ID: sub
        Tenant-ID: tenant

This chain:

  1. JWT middleware extracts claims (sub, tenant) and forwards them as headers
  2. Query Parameter middleware converts those headers to query parameters (user_id, tenant_id)
  3. Headers middleware removes the intermediate headers to clean up the request

The final request reaches the backend with the query parameters instead of headers, while keeping the original JWT token intact.

Middleware Chaining​

Since each Query Parameter middleware instance can only perform one operation type, you can chain multiple instances for complex transformations:

Chaining multiple Query Parameter middlewares for complex transformations
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: api-with-query-transformation
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`api.example.com`)
      kind: Rule
      middlewares:
        - name: remove-debug      # First: remove debug parameters
        - name: rename-legacy     # Second: rename legacy parameters
        - name: add-tracking      # Third: add tracking parameters
      services:
        - name: api-service
          port: 80

This approach allows you to build sophisticated query parameter transformations by combining individual operations.

Reusable Chain Middlewares​

For common patterns, especially when managing APIs at scale, creating reusable Chain middlewares significantly improves the user experience. Instead of managing multiple individual middlewares across many routes, you can create pre-configured chains for specific use cases.

JWT Claims to Query Parameters Chain​

A common enterprise pattern is extracting user context from JWT tokens and passing it as query parameters to backend services. Here's how to create a reusable chain for this:

Reusable chain for JWT claims extraction
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: jwt-claims-to-query-chain
  namespace: default
spec:
  chain:
    middlewares:
      - name: jwt-auth
      - name: extract-claims-to-query
      - name: cleanup-intermediate-headers

Using the Chain​

Once created, this chain can be applied to any route with a single middleware reference:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: user-service
spec:
  entryPoints: websecure
  routes:
    - match: Host(`users.example.com`)
      kind: Rule
      middlewares:
      # Single reference
        - name: jwt-claims-to-query-chain
      services:
        - name: user-service
          port: 80

This reusable chain demonstrates a complete authentication-to-query-parameters flow that automatically extracts user context from JWT tokens and makes it available to your backend services.

Request Flow Example​

When a client makes an authenticated request, the middleware chain processes it through three stages:

1. Initial Request:

GET /api/users HTTP/1.1
Host: users.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

2. JWT Middleware Processing: The JWT middleware validates the token and extracts claims as headers:

# JWT Token Claims:
{
  "sub": "user123",
  "tenant": "acme-corp",
  "role": "admin"
}

# Forwarded as Headers:
User-ID: user123
Tenant-ID: acme-corp
User-Role: admin

3. Query Parameter Extraction:

The Query Parameter middleware converts headers to query parameters:

GET /api/users?user_id=user123&tenant_id=acme-corp&user_role=admin HTTP/1.1
Host: users.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
User-ID: user123
Tenant-ID: acme-corp
User-Role: admin

4. Final Backend Request:

After header cleanup, your backend service receives:

GET /api/users?user_id=user123&tenant_id=acme-corp&user_role=admin HTTP/1.1
Host: users.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Related Content​