> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Transformer plugin

> Reference for the Transformer plugin, which changes headers, query parameters, cookies, and JSON body fields.

The Transformer plugin changes request headers, query parameters, cookies, and JSON body fields before the gateway forwards the request. It can also change response headers, status, cookies, and JSON body fields. Rules run in the order you list them. Transformer is a Preview plugin.

> **Note**
>
> On an Enterprise data plane, Transformer needs the OPA policy sidecar, which the Helm chart turns on with `opa.enabled`. It's off by default, and Transformer has no in-process fallback. Without the sidecar, the plugin fails according to its `on_error` setting, which defaults to `fail_closed`, so the request fails. The data plane must allow Preview plugins. For more information, see [Helm values](/run/helm-values).

## Where it runs

|             |                                                                                                                 |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| Protocols   | Request rules: all. Response rules: HTTP routes only, for responses that aren't streamed and are at most 1 MiB. |
| Scope kinds | `global`, `service`, `route`. The API also accepts `consumer`, but the console doesn't offer it.                |
| Phase       | Request and response                                                                                            |

Only the instance at the narrowest scope runs.

## Configuration

**`rules`** `array of objects`

The changes to make, in order. A rule whose target starts with `response.` runs on the response.

---

**`rules[].op`** `string` — required

The operation. See the list after this table.

---

**`rules[].target`** `string` — required

What to change: `request.method`, `request.path`, `request.header.<name>`, `request.query.<name>`, `request.body.<path>`, `request.cookie.<name>`, `response.header.<name>`, `response.status`, `response.body.<path>`, or `response.cookie.<name>`. `headers` and `cookies` work as plural forms, for example `request.headers.<name>`. `request.method` takes only `set`, `template`, `copy`, `move`, and `rename`. `request.path` takes only `set` and `template`, and each value substituted into a path template is escaped as one path segment.

---

**`rules[].value`** `string`

The value for `set`, `add`, `default`, and `template`. A value written to a body field is stored as JSON when it parses as JSON, otherwise as a string.

---

**`rules[].from`** `string`

The source for `copy`, `move`, `rename`, and `hash`, for example `identity.consumer`, `request.header.<name>`, or `request.body.<path>`.

---

**`rules[].cookie`** `object`

For response cookie targets only: `path`, `domain`, `max_age`, `secure`, `http_only`, and `same_site` (`lax`, `strict`, or `none`).

---

The operations do the following:

* `set` replaces the target with `value`.
* `add` adds `value` beside existing header or query values.
* `default` sets `value` only if the target is absent.
* `remove` deletes the target. `add` and `remove` aren't valid on `response.status`, and `default` on a response cookie always sets the value.
* `copy` sets the target to the value of `from`.
* `move` and `rename` copy, then delete the source when it's a header, query parameter, body field, or request cookie.
* `template` sets the target to `value` with every `{{ reference }}` replaced, for example `{{ identity.consumer }}`.
* `hash` sets the target to the lowercase hexadecimal SHA-256 of `from`, or of the target itself when `from` is omitted.

The `Authorization` header, and headers that the gateway fills with credentials, can't be read as sources.

## Example

```json
{
  "name": "add-caller-header",
  "plugin_id": "transformer",
  "scope": { "kind": "route", "name": "orders-api" },
  "config": {
    "rules": [
      { "op": "set", "target": "request.header.X-Api-Key", "value": "prod" },
      { "op": "copy", "target": "request.header.X-Caller", "from": "identity.consumer" },
      { "op": "remove", "target": "response.header.Server" }
    ]
  }
}
```

## Related guides

* [Control traffic with plugins](/configure/plugins#example-rewrite-a-header-with-the-transformer-plugin)