> ## 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.

# Headers

> Header requirements and options for Prisma AIRS AI Gateway API

AI Gateway API accepts 4 kinds of headers for your requests:

| | | |
| :- | :- | :- |
| AI Gateway Authentication Header | `Required` | For AI Gateway auth |
| Provider Authentication Headers OR Cloud-Specific Headers | `Required` | For provider auth |
| Additional AI Gateway Headers | `Optional` | To pass `config`, `metadata`, `trace id`, `cache refresh` etc. |
| Custom Headers | `Optional` | To forward any other headers directly |

## AI Gateway Authentication

### AI Gateway API Key

**Authorization / api\_key / apiKey** `string` *required*

Authenticate your requests with your AI Gateway API key, passed as `Bearer $PORTKEY_API_KEY`. Obtain API key from the [Strata Cloud Manager](https://stratacloudmanager.paloaltonetworks.com/).\\

Environment variable: `PORTKEY_API_KEY`

> [!NOTE]
>
> The `x-portkey-api-key` header remains active and continues to authenticate requests. `Authorization` is the standard way to authenticate into the gateway; use `x-portkey-api-key` when `Authorization` is already carrying provider credentials, as in [Provider Slug + Auth](#1-provider-slug-auth) below.

> **Example**
>
> ```sh cURL {2} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
> ```

## Provider Authentication

In addition to the AI Gateway API key, you must provide information about the AI provider you're using. There are **4** ways to do this:

### 1. Provider Slug + Auth

Useful if you do not want to save your API keys to the AI Gateway vault and make direct requests.

**x-portkey-provider / provider** `string`

Specifies the provider you're using (e.g., `openai`, `anthropic`, `vertex-ai`).\\

List of [the AI Gateway supported providers here](https://docs.portkey.ai/docs/aigw/integrations/llms.md).

**Authorization** `string`

Pass the auth details for the specified provider as a `"Bearer $TOKEN"`.\
\\

If your provider expects their auth with headers such as `x-api-key` or `api-key`, you can pass the token with the `Authorization` header directly and the AI Gateway will convert it into the provider-specific format.

> [!WARNING]
>
> Here `Authorization` carries the **provider** credential, so authenticate into the gateway with the `x-portkey-api-key` header instead. The provider authentication methods that resolve a provider from the Model Catalog leave `Authorization` free for your AI Gateway API key.

> **Example**
>
> ```sh cURL {3,4} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "x-portkey-api-key: $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: openai" \
>   -H "Authorization: Bearer $OPENAI_API_KEY" \
> ```

### 2. AI Provider

**x-portkey-provider / provider** `string`

Specify your AI Provider slug (from [Model Catalog](https://docs.portkey.ai/docs/aigw/product/model-catalog.md)) to route requests through a managed provider. Use the `@provider-slug` format. ([Docs](https://docs.portkey.ai/docs/aigw/product/model-catalog.md))

> [!NOTE]
>
> You usually do not need this header. Prefixing the model with the slug — `"model": "@openai-prod/gpt-4o"` — selects the provider inline and is the form used throughout these docs. Use the header when the endpoint takes no `model` parameter, such as Files and Batches, or when you are routing with a bare provider name and passing the provider's own credential in `Authorization`.

> [!NOTE]
>
> The `x-portkey-virtual-key` / `virtual_key` / `virtualKey` parameter is the legacy equivalent and still works for backward compatibility.

> **Example**
>
> ```sh cURL {3} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
> ```

### 3. Config

**x-portkey-config / config** `string or JSON`

Pass your AI Gateway config with this header. Accepts a `JSON object` or a `config ID` that can also contain gateway configuration settings, and provider details.\\

* Configs can be saved in Strata Cloud Manager and referenced by their ID ([Docs](https://docs.portkey.ai/docs/aigw/product/ai-gateway/configs.md))
* Configs also enable other optional features like Caching, Load Balancing, Fallback, Retries, and Timeouts.

> **Example**
>
> ```sh cURL {3} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-config: openai-config" \
> ```

### 4. Custom Host

**x-portkey-custom-host / custom\_host / customHost** `string`

Specifies the base URL where you want to send your request. The AI Gateway validates custom host URLs and blocks private/reserved IP ranges by default. See [Custom hosts](https://docs.portkey.ai/docs/aigw/product/ai-gateway/custom-hosts.md) for details.

**x-portkey-provider / provider** `string`

Target provider that's availabe on your base URL. If you are unsure of which target provider to set, you can set `openai`.

**Authorization** `string`

Pass the auth details for the specified provider as a `"Bearer $TOKEN"`.\
\\

If your provider expects their auth with headers such as `x-api-key` or `api-key`, you can pass the token with the `Authorization` header directly and the AI Gateway will convert it into the provider-specific format.

> [!WARNING]
>
> Here `Authorization` carries the **provider** credential, so authenticate into the gateway with the `x-portkey-api-key` header instead. The provider authentication methods that resolve a provider from the Model Catalog leave `Authorization` free for your AI Gateway API key.

> **Example**
>
> ```sh cURL {3-5} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "x-portkey-api-key: $PORTKEY_API_KEY" \
>   -H "x-portkey-custom-host: http://124.124.124.124/v1" \
>   -H "x-portkey-provider: openai" \
>   -H "Authorization: Bearer $TOKEN" \
> ```

***

## Additional AI Gateway Headers

There are additional optional AI Gateway headers that enable various features and enhancements:

### Trace ID

**x-portkey-trace-id / trace\_id / traceId** `string`

An ID you can pass to refer to one or more requests later on. If not provided, the AI Gateway generates a trace ID automatically for each request. ([Docs](https://docs.portkey.ai/docs/aigw/product/observability/traces.md))

> **Example**
>
> ```sh cURL {4} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "x-portkey-trace-id: test-request" \
> ```

### Metadata

**x-portkey-metadata / metadata** `JSON`

Allows you to attach custom metadata to your requests, which can be filtered later in the analytics and log dashboards.\\

You can include the special metadata type `_user` to associate requests with specific users. ([Docs](https://docs.portkey.ai/docs/aigw/product/observability/metadata.md))

> **Example**
>
> ```sh cURL {4} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "x-portkey-metadata: {'_user': 'user_id_123', 'foo': 'bar'}" \
> ```

### Cache Force Refresh

**x-portkey-cache-force-refresh / cache\_force\_refresh / cacheForceRefresh** `boolean`

Forces a cache refresh for your request by making a new API call and storing the updated value.\\

Expects `true` or `false` See the caching documentation for more information. ([Docs](https://docs.portkey.ai/docs/aigw/product/ai-gateway/cache-simple-and-semantic.md))

> **Example**
>
> ```sh cURL {4} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "x-portkey-cache-force-refresh: true" \
> ```

### Cache Namespace

**x-portkey-cache-namespace / cache\_namespace / cacheNamespace** `string`

Partition your cache store based on custom strings, ignoring metadata and other headers.

> **Example**
>
> ```sh cURL {4} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "x-portkey-cache-namespace: any-string" \
> ```

### Request Timeout

**x-portkey-request-timeout / request\_timeout / requestTimeout** `integer`

Set timeout after which a request automatically terminates. The time is set in milliseconds.

> **Example**
>
> ```sh cURL {4} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "x-portkey-request-timeout: 3000" \
> ```

### Fetch Integrated Models

**x-portkey-fetch-integrated-models** `boolean`

Applies to `GET /v1/models` only. When `true`, forces the endpoint to return the AI Gateway's integrated (Model Catalog) models even when a provider or config is passed on the request. Without this header, any provider signal causes the endpoint to proxy to the upstream provider's `/v1/models`. You can also set this as `fetch_integrated_models: true` inside an AI Gateway config. ([Docs](https://docs.portkey.ai/docs/aigw/api-reference/models/list-models.md))

> **Example**
>
> ```sh cURL {4} theme={"system"}
> curl https://aigw.portkey.ai/v1/models \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "x-portkey-fetch-integrated-models: true"
> ```
>
> ```json Config theme={"system"}
> {
>   "fetch_integrated_models": true,
>   "targets": [
>     { "provider": "@openai-prod" },
>     { "provider": "@anthropic-prod" }
>   ]
> }
> ```

## Custom Headers

You can pass any other headers your API expects by directly forwarding them without any processing by the AI Gateway.\

This is especially useful if you want to pass send sensitive headers.

### Forward Headers

**x-portkey-forward-headers / forward\_headers / forwardHeaders** `array of strings`

Pass all the headers you want to forward directly in this array. (Docs)

> **Example**
>
> ```sh cURL {4-6} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "X-Custom-Header: ...."\
>   -H "Another-Header: ....."\
>   -H "x-portkey-forward-headers: ['X-Custom-Header', 'Another-Header']" \
> ```
>
> > [!NOTE]
> >
> > #### Python Usage
> >
> > With the Python SDK, you need to transform your headers to **Snake Case** and then include them while initializing the AI Gateway client.
> > Example: If you have a header of the format `X-My-Custom-Header`, it should be sent as `X_My_Custom_Header` in the SDK.
> >
> > **Note:** When using `forward_headers`, ensure the header names in the list are in their **original format** (e.g., `X-My-Custom-Header`), not the snake case format.
> >
> > #### JavaScript Usage
> >
> > With the JS SDK, you need to transform your headers to **Camel Case** and then include them while initializing the AI Gateway client.
> > Example: If you have a header of the format `X-My-Custom-Header`, it should be sent as `xMyCustomHeader` in the SDK

### Mask Sensitive Headers in Logs

**x-portkey-sensitive-headers / sensitive\_headers / sensitiveHeaders** `array of strings`

List of header names whose values the AI Gateway should mask (hash) in request, response, and trace logs. Matching is case-insensitive.

`x-portkey-sensitive-headers` only controls log masking. It does **not** forward headers to the upstream provider.

If you need both behaviours, use:

* `x-portkey-forward-headers` to forward the header upstream
* `x-portkey-sensitive-headers` to mask that header's value in AI Gateway logs

For organisation-wide defaults, set `ORGANISATION_HEADERS_TO_MASK` (comma-separated header names) in your gateway environment to mask matching headers across requests.

> **Example**
>
> ```sh cURL {5} theme={"system"}
> curl https://aigw.portkey.ai/v1/chat/completions \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @openai-prod" \
>   -H "X-Internal-Token: supersecret" \
>   -H "x-portkey-sensitive-headers: X-Internal-Token"
> ```

## Cloud-Specific Headers (`Azure`, `Google`, `AWS`)

Pass more configuration headers for `Azure OpenAI`, `Google Vertex AI`, or `AWS Bedrock`

### Azure

* `x-portkey-azure-resource-name`, `x-portkey-azure-deployment-id`, `x-portkey-azure-api-version`, `Authorization`, `x-portkey-azure-model-name`

### Google Vertex AI

* `x-portkey-vertex-project-id`, `x-portkey-vertex-region`, `X-Vertex-AI-LLM-Request-Type`

### AWS Bedrock

* `x-portkey-aws-session-token`, `x-portkey-aws-secret-access-key`, `x-portkey-aws-region`, `x-portkey-aws-session-token`

***

## List of All Headers

The following is a comprehensive list of headers that can be used when initializing the AI Gateway client.

The AI Gateway adheres to language-specific naming conventions:

* **camelCase** for **JavaScript/Node.js** parameters
* **snake\_case** for **Python** parameters
* **hyphenated-keys** for **HTTP headers**

**NodeJS**

| Parameter | Type | Key |
| :- | :- | :- |
| **API Key** Your AI Gateway account's API Key. | stringrequired | `apiKey` |
| **Virtual Key** *(Legacy — use `provider` with `@provider-slug` instead)* | string | `virtualKey` |
| **Config** The slug or [config object](https://docs.portkey.ai/docs/aigw/api-reference/inference-api/config-object.md) to use | stringobject | `config` |
| **Provider** The AI provider to use for your calls. ([supported providers](https://docs.portkey.ai/docs/aigw/integrations/llms.md#supported-ai-providers)). | string | `provider` |
| **Base URL** You can edit the URL of the gateway to use. Needed if you're [self-hosting the AI gateway](https://docs.portkey.ai/docs/aigw/self-hosting/hybrid-deployments/architecture.md) | string | `baseURL` |
| **Trace ID** An ID you can pass to refer to 1 or more requests later on. Generated automatically for every request, if not sent. | string | `traceID` |
| **Metadata** Any metadata to attach to the requests. These can be filtered later on in the analytics and log dashboards Can contain `_prompt`, `_user`, `_organisation`, or `_environment` that are special metadata types in the AI Gateway. You can also send any other keys as part of this object. | object | `metadata` |
| **Cache Force Refresh** Force refresh the cache for your request by making a new call and storing that value. | boolean | `cacheForceRefresh` |
| **Cache Namespace** Partition your cache based on custom strings, ignoring metadata and other headers. | string | `cacheNamespace` |
| **Custom Host** Route to locally or privately hosted model by configuring the API URL with custom host | string | `customHost` |
| **Forward Headers** Forward sensitive headers directly to your model's API without any processing from the AI Gateway. | array of string | `forwardHeaders` |
| **Azure OpenAI Headers** Configuration headers for Azure OpenAI that you can send separately | string | `azureResourceName` `azureDeploymentId` `azureApiVersion` `azureModelName` |
| **Google Vertex AI Headers** Configuration headers for Vertex AI that you can send separately | string | `vertexProjectId` `vertexRegion` |
| **AWS Bedrock Headers** Configuration headers for Bedrock that you can send separately | string | `awsAccessKeyId` `awsSecretAccessKey` `awsRegion` `awsSessionToken` |

**Python**

| Parameter | Type | Key |
| :- | :- | :- |
| **API Key** Your AI Gateway account's API Key. | stringrequired | `api_key` |
| **Virtual Key** *(Legacy — use `provider` with `@provider-slug` instead)* | string | `virtual_key` |
| **Config** The slug or [config object](https://docs.portkey.ai/docs/aigw/api-reference/inference-api/config-object.md) to use | stringobject | `config` |
| **Provider** The AI provider to use for your calls. ([supported providers](https://docs.portkey.ai/docs/aigw/integrations/llms.md#supported-ai-providers)). | string | `provider` |
| **Base URL** You can edit the URL of the gateway to use. Needed if you're [self-hosting the AI gateway](https://docs.portkey.ai/docs/aigw/self-hosting/hybrid-deployments/architecture.md) | string | `base_url` |
| **Trace ID** An ID you can pass to refer to 1 or more requests later on. Generated automatically for every request, if not sent. | string | `trace_id` |
| **Metadata** Any metadata to attach to the requests. These can be filtered later on in the analytics and log dashboards Can contain `_prompt`, `_user`, `_organisation`, or `_environment` that are special metadata types in the AI Gateway. You can also send any other keys as part of this object. | object | `metadata` |
| **Cache Force Refresh** Force refresh the cache for your request by making a new call and storing that value. | boolean | `cache_force_refresh` |
| **Cache Namespace** Partition your cache based on custom strings, ignoring metadata and other headers. | string | `cache_namespace` |
| **Custom Host** Route to locally or privately hosted model by configuring the API URL with custom host | string | `custom_host` |
| **Forward Headers** Forward sensitive headers directly to your model's API without any processing from the AI Gateway. | array of string | `forward_headers` |
| **Azure OpenAI Headers** Configuration headers for Azure OpenAI that you can send separately | string | `azure_resource_name` `azure_deployment_id` `azure_api_version` `azure_model_name` |
| **Google Vertex AI Headers** Configuration headers for Vertex AI that you can send separately | string | `vertex_project_id` `vertex_region` |
| **AWS Bedrock Headers** Configuration headers for Bedrock that you can send separately | string | `aws_access_key_id` `aws_secret_access_key` `aws_region` `aws_session_token` |

**REST Headers**

| Parameter | Type | Header Key |
| :- | :- | :- |
| **API Key** Your AI Gateway account's API Key. | stringrequired | `x-portkey-api-key` |
| **Virtual Key** *(Legacy — use `x-portkey-provider` with `@provider-slug` instead)* | string | `x-portkey-virtual-key` |
| **Config** The slug or [config object](https://docs.portkey.ai/docs/aigw/api-reference/inference-api/config-object.md) to use | string | `x-portkey-config` |
| **Provider** The AI provider to use for your calls. ([supported providers](https://docs.portkey.ai/docs/aigw/integrations/llms.md#supported-ai-providers)). | string | `x-portkey-provider` |
| **Base URL** You can edit the URL of the gateway to use. Needed if you're [self-hosting the AI gateway](https://docs.portkey.ai/docs/aigw/self-hosting/hybrid-deployments/architecture.md) | string | Change the request URL |
| **Trace ID** An ID you can pass to refer to 1 or more requests later on. Generated automatically for every request, if not sent. | string | `x-portkey-trace-id` |
| **Metadata** Any metadata to attach to the requests. These can be filtered later on in the analytics and log dashboards Can contain `_prompt`, `_user`, `_organisation`, or `_environment` that are special metadata types in the AI Gateway. You can also send any other keys as part of this object. | string | `x-portkey-metadata` |
| **Cache Force Refresh** Force refresh the cache for your request by making a new call and storing that value. | boolean | `x-portkey-cache-force-refresh` |
| **Cache Namespace** Partition your cache based on custom strings, ignoring metadata and other headers | string | `x-portkey-cache-namespace` |
| **Custom Host** Route to locally or privately hosted model by configuring the API URL with custom host | string | `x-portkey-custom-host` |
| **Forward Headers** Forward sensitive headers directly to your model's API without any processing from the AI Gateway. | array of string | `x-portkey-forward-headers` |
| **Azure OpenAI Headers** Configuration headers for Azure OpenAI that you can send separately | string | `x-portkey-azure-resource-name`, `x-portkey-azure-deployment-id`, `x-portkey-azure-api-version`, `x-portkey-azure-model-name` |
| **Google Vertex AI Headers** Configuration headers for Vertex AI that you can send separately | string | `x-portkey-vertex-project-id`, `x-portkey-vertex-region` |
| **AWS Bedrock Headers** Configuration headers for Bedrock that you can send separately | string | `x-portkey-aws-session-token`, `x-portkey-aws-secret-access-key`, `x-portkey-aws-region`, `x-portkey-aws-session-token` |

### Using Headers

You can send these headers in multiple ways:

```sh REST API theme={"system"}
curl https://aigw.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer PORTKEY_API_KEY" \
  -H "x-portkey-trace-id: your_trace_id" \
  -H "x-portkey-metadata: {\"_user\": \"user_12345\"}" \
  -d '{
    "model": "@openai-prod/gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

```python OpenAI SDK theme={"system"}
# Python
from openai import OpenAI

# At initialization
client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url="https://aigw.portkey.ai/v1"
)

# At runtime
response = client.with_options(
    extra_headers={"x-portkey-trace-id": "your_trace_id",
                  "x-portkey-metadata": '{"_user": "user_12345"}'}
).chat.completions.create(
    model="@openai-prod/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

```js OpenAI Node.js SDK theme={"system"}
// Node.js
import OpenAI from "openai";

// At initialization
const client = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: "https://aigw.portkey.ai/v1"
});

// At runtime
const response = await client.chat.completions.create(
    {
        model: "@openai-prod/gpt-4o",
        messages: [{ role: "user", content: "Hello!" }]
    },
    {
        headers: {
            "x-portkey-trace-id": "your_trace_id",
            "x-portkey-metadata": JSON.stringify({"_user": "user_12345"})
        }
    }
);
```


## Related topics

- [Forwarding Headers](https://docs.portkey.ai/docs/aigw/product/mcp-gateway/authentication/forwarding-headers.md)
- [Bring Your Own Guardrails](https://docs.portkey.ai/docs/aigw/integrations/guardrails/bring-your-own-guardrails.md)
- [Custom Auth](https://docs.portkey.ai/docs/aigw/product/mcp-gateway/authentication/custom-auth.md)
- [Creating Raw Guardrails (in JSON)](https://docs.portkey.ai/docs/aigw/product/guardrails/creating-raw-guardrails-in-json.md)


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