Request Transformer

Overview

The Request Transformer policy is an inbound policy, and it enables dynamic modification of incoming HTTP requests before they are forwarded to upstream services. This includes the ability to:

• Remove or add headers, query strings, and body parameters.
• Rename or replace specific request fields.
• Apply transformation logic using templates or static values.

This is useful in scenarios such as adapting APIs to legacy systems, adding or masking sensitive information, or supporting evolving API contracts.

Kong Gateway processes request transformations in the following order:

1. Remove
2. Rename
3. Replace
4. Add
5. Append

Configuration Details

The user interface provides dynamic configuration inputs. You can add multiple transformation lines by clicking the green plus icon.

Supported Transformation Types

Field	Format	Description
config.remove.headers	x-remove-header	Removes specified headers.
config.remove.querystring	param1,param2	Removes specific query params.
config.remove.body	param1,param2	Removes specific form fields.
config.rename.headers	old:new	Renames a header.
config.rename.querystring	old:new	Renames a query param.
config.rename.body	old:new	Renames a body field.
config.replace.headers	key:value	Replaces header value.
config.replace.querystring	key:value	Replaces query param value.
config.replace.body	key:value	Replaces body field value.
config.add.headers	key:value	Adds a new header.
config.add.querystring	key:value	Adds a new query param.
config.add.body	key:value	Adds a new form field.
config.append.headers	key:value	Appends to existing header values.
config.append.querystring	key:value	Appends to existing query param values.
config.append.body	key:value	Appends to existing body param values.

• If a field’s value contains a comma, use array notation instead of comma-separated strings.

e.g., headers[1]=h1:v1

• The x-forwarded-* headers (added by Nginx) cannot be modified with this plugin.
• For all config types, list items must follow the "key:value" format or "old:new" for renames.

Templates

You can use templates to dynamically inject values from the incoming request:

Header:

${headers.<header_name>}

Query:

${query_params.<param_name>}

URI Capture:

${uri_captures.<group_name>}

Shared:

${shared.<variable_name>}

You can even use Lua expressions inside templates like:

Authorization:$(function()
	local value = headers.Authorization
	if not value then return end
	if value:sub(1,6) == "Basic " then return value end
	return "Basic " .. value
end())

Examples

Basic Request Transformation

Transform an incoming request by removing a header, renaming a body field, and adding a query parameter:

{
	"name": "request-transformer",
	"config": {
		"remove": {
		"headers": ["x-remove-header"],
		"body": ["formparam-toremove"],
		"querystring": ["qs-toremove"]
		},
		"rename": {
		"body": ["param-old:param-new"]
		},
		"add": {
		"querystring": ["new-param:some_value"],
		"headers": ["x-new-header:some_value"]
		}
	}
}

Enabling via Kong Admin API

curl -X POST [http://localhost:8001/services/{serviceName}/plugins](http://localhost:8001/services/%7BserviceName%7D/plugins) \
--data "name=request-transformer" \
--data "config.add.body=new-field:defaultvalue"

Append and Remove in One Request

curl -X POST [http://localhost:8001/services/example-service/plugins](http://localhost:8001/services/example-service/plugins) \
--data "name=request-transformer" \
--data "config.append.headers=h1:v2,h2:v1" \
--data "config.remove.body=p1"

Using URI Capture Templates

--data "config.add.headers=x-user-id:${uri_captures['user_id']}"

Multiple Headers (as array)

--data "config.add.headers[1]=h1:v1" \
--data "config.add.headers[2]=h2:v1"

This plugin is highly flexible and plays a critical role in bridging differences between client expectations and upstream API specifications.

For more instructions and advanced examples of using the policy, please refer to this guide: Request Transformer - Plugin | Kong Docs