> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Forwarding Headers

> Pass headers from client requests through to your agents.

By default, Portkey sends only the headers configured on the agent integration to the upstream agent. Header forwarding passes selected headers from the client request through as well. Use it for distributed tracing, tenant context, or per-request metadata your agent expects.

It works the same way as [header forwarding for MCP servers](https://docs.portkey.ai/docs/product/mcp-gateway/authentication/forwarding-headers.md), including inline renaming.

Common scenarios:

* **Distributed tracing.** Forward `x-request-id`, `x-trace-id` or `traceparent` to correlate logs across services.
* **Multi-tenancy.** Forward `x-tenant-id` or `x-org-id` for tenant-scoped operations.
* **User context.** Forward `x-user-id` or `x-user-role` for upstream authorization.

***

## Configuration

Set `forward_headers` in the agent integration's `configurations`, or use **Forward Caller Headers** when adding or editing an agent in the Agent Registry.

### Shorthand (string array)

Forward only the headers you list:

```json theme={"system"}
{
  "configurations": {
    "forward_headers": ["x-request-id", "x-trace-id", "x-tenant-id"]
  }
}
```

All other client headers are dropped.

### Allowlist mode

Entries in `headers` can be:

* **A string**: forwards the header as-is.
* **An object** `{ "from": "<client_header>", "to": "<agent_header>" }`: forwards the header under a new name.

```json theme={"system"}
{
  "configurations": {
    "forward_headers": {
      "mode": "allowlist",
      "headers": [
        "x-trace-id",
        { "from": "x-tenant-id", "to": "X-Organization-Id" }
      ]
    }
  }
}
```

Here `x-trace-id` is forwarded as-is and `x-tenant-id` reaches the agent as `X-Organization-Id`.

### All-except mode

Forward every client header except the ones you list. String entries are excluded; object entries rename forwarded headers:

```json theme={"system"}
{
  "configurations": {
    "forward_headers": {
      "mode": "all-except",
      "headers": [
        "x-internal-debug",
        { "from": "x-tenant-id", "to": "X-Org-Id" }
      ]
    }
  }
}
```

> [!WARNING]
>
> `all-except` forwards more than you might expect, including the client's `Authorization` header if the integration does not set its own. Prefer an explicit allowlist when possible.

***

## Headers that are never forwarded

These headers are dropped regardless of your configuration.

**Protected headers**, the same list as for MCP servers. A rename is dropped if either its source or its target is protected:

`cookie`, `set-cookie`, `x-api-key`, `x-portkey-api-key`, `api-key`, `apikey`, `x-auth-token`, `x-access-token`, `x-user-claims`, `x-user-jwt`

**Connection headers**, which describe the client's connection to Portkey rather than Portkey's request to the agent. They are never sent to the agent, including as a rename target:

`host`, `connection`, `keep-alive`, `proxy-connection`, `transfer-encoding`, `te`, `trailer`, `upgrade`, `content-length`, `expect`, `accept-encoding`

Header names are matched case-insensitively.

***

## Header priority

Headers configured on the integration always win over forwarded ones:

| Priority | Source |
| - | - |
| 1 (lowest) | Forwarded client headers |
| 2 | `headers` configured on the integration (authentication) |
| 3 (highest) | `passthrough_headers` configured on the integration |

If a configured header and a forwarded header share a name, in any case, only the configured value is sent. Clients cannot override the agent's credentials.

***

## Example

**Integration configuration:**

```json theme={"system"}
{
  "configurations": {
    "headers": { "Authorization": "Bearer <agent-api-key>" },
    "forward_headers": {
      "mode": "allowlist",
      "headers": [
        "A2A-Version",
        "x-trace-id",
        { "from": "x-user-token", "to": "x-upstream-token" }
      ]
    }
  }
}
```

**Client request:**

```sh theme={"system"}
curl https://agents.portkey.ai/v1/agent/my-agent/a2a/jsonrpc \
  -H 'x-portkey-api-key: {PORTKEY_API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'A2A-Version: 1.0' \
  -H 'x-trace-id: trace-xyz789' \
  -H 'x-user-token: user-abc' \
  -H 'x-debug: 1' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "SendMessage", "params": {"message": {"role": "user", "messageId": "msg-001", "parts": [{"text": "Hello, agent!"}]}}}'
```

**Agent receives:**

```
Authorization: Bearer <agent-api-key>
A2A-Version: 1.0
x-trace-id: trace-xyz789
x-upstream-token: user-abc
```

`x-debug` is not on the allowlist, and `x-portkey-api-key` is protected, so neither is forwarded.

> [!NOTE]
>
> Forwarded headers apply to requests proxied to the agent. They are not sent when Portkey fetches the agent card.

***

## Related

| Topic | Description |
| - | - |
| [Agent Registry](https://docs.portkey.ai/docs/product/agent-gateway/registry.md) | Manage agent integrations |
| [MCP header forwarding](https://docs.portkey.ai/docs/product/mcp-gateway/authentication/forwarding-headers.md) | The same feature for MCP servers |

***

> [card] [Portkey is now PRISMA AIRS AI Gateway. See it in action.](https://www.paloaltonetworks.in/ai-security/ai-gateway?utm_source=portkey\&utm_medium=referral\&utm_campaign=prisma_airs\&utm_content=docs_nav#contact)
>
> Contact Us


## Related topics

- [Forwarding Headers](https://docs.portkey.ai/docs/product/mcp-gateway/authentication/forwarding-headers.md)
- [Authentication](https://docs.portkey.ai/docs/product/mcp-gateway/authentication.md)
- [Identity Forwarding](https://docs.portkey.ai/docs/product/mcp-gateway/authentication/identity-forwarding.md)
- [Creating Raw Guardrails (in JSON)](https://docs.portkey.ai/docs/product/guardrails/creating-raw-guardrails-in-json.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.