Forwarding Headers

Header forwarding passes specific client headers through to your guardrail providers. Use it for trace correlation, session-aware policy enforcement, or custom context your provider expects. Without forwarding configured, only Content-Type and the provider’s authentication reach the guardrail endpoint. All other client headers stop at Portkey.

Configuration

Add forwardHeaders to any external check’s parameters. List the exact header names you want forwarded:

{
  "checks": [
    {
      "id": "default.webhook",
      "parameters": {
        "webhookURL": "https://guardrails.example.com/check",
        "forwardHeaders": ["x-portkey-trace-id", "traceparent", "x-session-id"]
      }
    }
  ]
}

If forwardHeaders is absent or omitted, nothing is forwarded. Each check configures forwarding independently. Provider authentication headers always take precedence — forwarded headers cannot overwrite them.

If you include traceparent in your list and the client sends x-portkey-trace-id but no traceparent, Portkey synthesizes a valid W3C traceparent automatically. If the client sends a valid traceparent directly, it passes through unchanged.

Restricted Headers

Portkey prevents forwarding headers that carry credentials or sensitive context. The following categories are blocked and rejected at save time:

Credentials — authorization, x-api-key, ocp-apim-subscription-key, proxy-authorization
Session — cookie
Cloud metadata — headers used by cloud IMDS endpoints (AWS, GCP)
Internal routing — all x-portkey-* headers except x-portkey-trace-id and x-portkey-span-id
Hop-by-hop — protocol headers like connection, host, transfer-encoding

Header names must be valid per RFC 7230 — lowercase alphanumeric characters and hyphens only. Wildcards are not supported.

Introduction

Product

Self-Hosting

Support

Configuration

Restricted Headers

Guardrails

Bring Your Own Guardrails

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

​Configuration

​Restricted Headers

​Related

Guardrails

Bring Your Own Guardrails

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

Configuration

Restricted Headers

Related