Document updated on Feb 19, 2026

Body to header and query string extractor

The Request Body Extractor reads one or more fields from an incoming request body and maps their values to request headers or query strings before KrakenD forwards the request upstream. You can place this transformation at three points in the processing pipeline: globally at the service level, early at the endpoint handling level before authentication runs, or inside the proxy pipeline where async agents and workflows also execute. This enables the promotion of authentication credentials, tenant identifiers, or routing parameters that clients embed in a JSON body to the standard positions where KrakenD components expect to find them.

Namespace and Pipeline Placement

The Request Body Extractor has two namespaces. Their placement in the extra_config configuration determines when extraction occurs relative to authentication and other pipeline stages:

When you place modifier/request-body-extractor at the service level, every request passes through the extractor regardless of which endpoint it targets. This is the right choice when all endpoints depend on the same body-derived parameter, for example, a global tenant identifier extracted into a query string.

At the endpoint level, the same namespace runs inside the proxy pipeline. This stage executes after the endpoint handling, so authentication has already occurred by the time extraction runs. Use this placement when the extracted value feeds into backend calls, sequential proxies, async agents, or workflow composition.

The early variant (modifier/request-body-extractor/early) runs at the endpoint handling level, before any other endpoint-related component, including auth/api-keys, auth/validator, and rate limiting. It is only available at the endpoint level and cannot participate in async agent pipelines. Use this namespace when the extracted value must be visible to an authentication or authorization component.

Configuring Extraction Operations

Both namespaces share the same configuration structure: an operations array where each element defines one extraction rule. You can declare multiple operations to populate several headers or query strings from a single request body.

Extraction Strategies

The dotnotation strategy navigates nested JSON objects using period-separated field names. For example, the expression user.id retrieves the id field nested inside a user object. Use dotnotation for straightforward field access without filtering or array traversal.

The jmespath strategy evaluates a JMESPath expression against the parsed request body. Use jmespath when the value is inside an array, requires conditional selection, aggregations, or involves more complex projections that dot notation cannot express.

Conflict Resolution

The on_conflict field controls behaviour when the destination header or query string parameter already holds a value at the time extraction runs:

• skip preserves the existing value and discards the extracted one. Use this to avoid overwriting headers set directly by the client.
• replace overwrites the existing value with the value extracted from the body.
• append adds the extracted value alongside the existing one. This is relevant for headers that accept multiple values.

Example: how to extract a body parameter as a header

When you place modifier/request-body-extractor at the endpoint level (without the /early suffix), the extraction runs inside the proxy pipeline. This is the correct placement when the extracted value feeds downstream components such as sequential proxies, async agents, or backend-level transformations:

{
  "endpoint": "/secure/regular/",
  "method": "POST",
  "output_encoding": "no-op",
  "input_headers": ["Authorization"],
  "extra_config": {
    "modifier/request-body-extractor": {
      "operations": [
        {
          "type": "header",
          "strategy": "dotnotation",
          "expression": "auth.role_key",
          "target": "Authorization",
          "on_conflict": "skip"
        }
      ]
    }
  },
  "backend": [
    {
      "url_pattern": "/customer",
      "method": "GET",
      "host": ["http://backend:8080"]
    }
  ]
}

Because the proxy pipeline runs after HTTP-level authentication, any component configured in the endpoint’s extra_config that operates at the endpoint handling level, such as auth/api-keys, does not see the header value injected here. If the extracted value must influence endpoint-level authentication, use modifier/request-body-extractor/early instead, as shown in the previous example.

Example: how to extract a body parameter for all requests

The following configuration extracts user.id from the request body globally and injects it as the query string parameter uid on every endpoint. If uid already exists in the request, it replaces it:

{
  "version": 3,
  "extra_config": {
    "modifier/request-body-extractor": {
      "operations": [
        {
          "type": "query_string",
          "strategy": "dotnotation",
          "expression": "user.id",
          "target": "uid",
          "on_conflict": "replace"
        }
      ]
    }
  },
  "endpoints": []
}

Every endpoint in the gateway receives the uid query string parameter derived from the body. For the parameter to reach the backend, each endpoint must also declare uid in its input_query_strings list.

Example: how to extract a body parameter before authentication

In this scenario, a client sends its API key inside the JSON body under auth.role_key instead of in an Authorization header. The modifier/request-body-extractor/early namespace extracts the field and writes it to Authorization before the API key validator runs:

{
  "endpoint": "/secure/early/",
  "method": "POST",
  "output_encoding": "no-op",
  "input_headers": ["Authorization"],
  "extra_config": {
    "modifier/request-body-extractor/early": {
      "operations": [
        {
          "type": "header",
          "strategy": "dotnotation",
          "expression": "auth.role_key",
          "target": "Authorization",
          "on_conflict": "skip"
        }
      ]
    },
    "auth/api-keys": {
      "roles": ["role1"]
    }
  },
  "backend": [
    {
      "url_pattern": "/sales",
      "method": "GET",
      "host": ["http://backend:8080"]
    }
  ]
}

The on_conflict: skip setting ensures that a client providing the Authorization header directly takes precedence over the body field. When the header is absent, KrakenD populates it from auth.role_key, and the API key validator proceeds with that value. Because modifier/request-body-extractor/early executes at the endpoint handling level, the auth/api-keys component sees the injected header without any additional wiring.