- Distributed tracing. Forward
x-request-id,x-trace-idortraceparentto correlate logs across services. - Multi-tenancy. Forward
x-tenant-idorx-org-idfor tenant-scoped operations. - User context. Forward
x-user-idorx-user-rolefor upstream authorization.
Configuration
Setforward_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:Allowlist mode
Entries inheaders can be:
- A string: forwards the header as-is.
- An object
{ "from": "<client_header>", "to": "<agent_header>" }: forwards the header under a new name.
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: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: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.
Related
Portkey is now PRISMA AIRS AI Gateway. See it in action.
Contact Us

