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 Prisma AIRS AI Gateway.

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, the AI Gateway synthesizes a valid W3C traceparent automatically. If the client sends a valid traceparent directly, it passes through unchanged.

Restricted Headers

The AI Gateway 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

Configuration

Restricted Headers

Guardrails

Bring Your Own Guardrails

​Configuration

​Restricted Headers

​Related

Guardrails

Bring Your Own Guardrails

Configuration

Restricted Headers

Related