Skip to main content
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, 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:
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.
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:
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: 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:
Client request:
Agent receives:
x-debug is not on the allowlist, and x-portkey-api-key is protected, so neither is forwarded.
Forwarded headers apply to requests proxied to the agent. They are not sent when Portkey fetches the agent card.


Portkey is now PRISMA AIRS AI Gateway. See it in action.

Contact Us
Last modified on November 11, 2026