Headers

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

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.
Environment variable: PORTKEY_API_KEY

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

Example

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.

string

Specifies the provider you’re using (e.g., openai, anthropic, vertex-ai).
List of the AI Gateway supported providers here.

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.

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

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

string

Specify your AI Provider slug (from Model Catalog) to route requests through a managed provider. Use the @provider-slug format. (Docs)

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.

The x-portkey-virtual-key / virtual_key / virtualKey parameter is the legacy equivalent and still works for backward compatibility.

Example

curl https://aigw.portkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @openai-prod" \

3. 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)
Configs also enable other optional features like Caching, Load Balancing, Fallback, Retries, and Timeouts.

Example

curl https://aigw.portkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $PORTKEY_API_KEY" \
  -H "x-portkey-config: openai-config" \

4. Custom Host

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 for details.

string

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

string

Example

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

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)

Example

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

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)

Example

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

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)

Example

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

string

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

Example

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

integer

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

Example

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

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)

Example

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"

{
  "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

array of strings

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

Example

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']" \

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

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 behaviors, 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

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
Python
REST Headers

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 to use	stringobject	`config`
Provider The AI provider to use for your calls. (supported providers).	string	`provider`
Base URL You can edit the URL of the gateway to use. Needed if you’re self-hosting the AI gateway	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`

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 to use	stringobject	`config`
Provider The AI provider to use for your calls. (supported providers).	string	`provider`
Base URL You can edit the URL of the gateway to use. Needed if you’re self-hosting the AI gateway	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`

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 to use	string	`x-portkey-config`
Provider The AI provider to use for your calls. (supported 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	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:

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
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!"}]
)

// 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"})
        }
    }
);

API Reference

Inference

AI Gateway Authentication

AI Gateway API Key

Provider Authentication

1. Provider Slug + Auth

2. AI Provider

3. Config

4. Custom Host

Additional AI Gateway Headers

Trace ID

Metadata

Cache Force Refresh

Cache Namespace

Request Timeout

Fetch Integrated Models

Custom Headers

Forward Headers

Python Usage

JavaScript Usage

Mask Sensitive Headers in Logs

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

Azure

Google Vertex AI

AWS Bedrock

List of All Headers

Using Headers

​AI Gateway Authentication

​AI Gateway API Key

​Provider Authentication

​1. Provider Slug + Auth

​2. AI Provider

​3. Config

​4. Custom Host

​Additional AI Gateway Headers

​Trace ID

​Metadata

​Cache Force Refresh

​Cache Namespace

​Request Timeout

​Fetch Integrated Models

​Custom Headers

​Forward Headers

​Python Usage

​JavaScript Usage

​Mask Sensitive Headers in Logs

​Cloud-Specific Headers (Azure, Google, AWS)

​Azure

​Google Vertex AI

​AWS Bedrock

​List of All Headers

​Using Headers

AI Gateway Authentication

AI Gateway API Key

Provider Authentication

1. Provider Slug + Auth

2. AI Provider

3. Config

4. Custom Host

Additional AI Gateway Headers

Trace ID

Metadata

Cache Force Refresh

Cache Namespace

Request Timeout

Fetch Integrated Models

Custom Headers

Forward Headers

Python Usage

JavaScript Usage

Mask Sensitive Headers in Logs

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

Azure

Google Vertex AI

AWS Bedrock

List of All Headers

Using Headers