Headers

Portkey API accepts 4 kinds of headers for your requests:


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

Portkey Authentication

Portkey API Key

x-portkey-api-key / api_key / apiKey

string

required

Authenticate your requests with your Portkey API key. Obtain API key from the Portkey dashboard.
Environment variable: PORTKEY_API_KEY

Example

Provider Authentication

In addition to the Portkey 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 Portkey vault and make direct requests.

x-portkey-provider / provider

string

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

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 Portkey will convert it into the provider-specific format.

Example

curl https://api.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. Virtual Key

x-portkey-virtual-key / virtual_key / virtualKey

string

Save your provider auth on Portkey and use a virtual key to directly make a call. Docs)

Example

3. Config

x-portkey-config / config

string or JSON

Pass your Portkey 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 the Portkey UI and referenced by their ID (Docs)
Configs also enable other optional features like Caching, Load Balancing, Fallback, Retries, and Timeouts.

Example

4. Custom Host

x-portkey-custom-host / custom_host / customHost

string

Specifies the base URL where you want to send your request

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

Example

curl https://api.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 Portkey Headers

There are additional optional Portkey 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, Portkey generates a trace ID automatically for each request. (Docs)

Example

curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -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)

Example

curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -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)

Example

curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -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

curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -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

curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -H "x-portkey-request-timeout: 3000" \

Custom Headers

You can pass any other headers your API expects by directly forwarding them without any processing by Portkey.
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

curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: openai-virtual-key" \
  -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 Portkey 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

JavaScript Usage

With the JS SDK, you need to transform your headers to Camel Case and then include them while initializing the Portkey client. Example: If you have a header of the format X-My-Custom-Header, it should be sent as xMyCustomHeader in the SDK

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 Portkey client. Portkey adheres to language-specific naming conventions:

camelCase for JavaScript/Node.js parameters
snake_case for Python parameters
hyphenated-keys for HTTP headers

Parameter	Type	Key
API Key Your Portkey account’s API Key.	stringrequired	`apiKey`
Virtual Key The virtual key created from Portkey’s vault for a specific provider	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 Portkey. 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 Portkey.	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`

Using Headers

You can send these headers in multiple ways:

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: PORTKEY_API_KEY" \
  -H "x-portkey-virtual-key: VIRTUAL_KEY" \
  -H "x-portkey-trace-id: your_trace_id" \
  -H "x-portkey-metadata: {\"_user\": \"user_12345\"}" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

API Reference

SDK

Chat Completions

Responses

Portkey Endpoints

Embeddings

Images

Audio

Other APIs

Completions

Moderations

Fine-tuning

Batch

Files

Assistants

Portkey Authentication

Portkey API Key

Provider Authentication

1. Provider Slug + Auth

2. Virtual Key

3. Config

4. Custom Host

Additional Portkey Headers

Trace ID

Metadata

Cache Force Refresh

Cache Namespace

Request Timeout

Custom Headers

Forward Headers

Python Usage

JavaScript Usage

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

Azure

Google Vertex AI

AWS Bedrock

List of All Headers

Using Headers

API Reference

SDK

Chat Completions

Responses

Portkey Endpoints

Embeddings

Images

Audio

Other APIs

Completions

Moderations

Fine-tuning

Batch

Files

Assistants

​Portkey Authentication

​Portkey API Key

​Provider Authentication

​1. Provider Slug + Auth

​2. Virtual Key

​3. Config

​4. Custom Host

​Additional Portkey Headers

​Trace ID

​Metadata

​Cache Force Refresh

​Cache Namespace

​Request Timeout

​Custom Headers

​Forward Headers

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

​Azure

​Google Vertex AI

​AWS Bedrock

​List of All Headers

​Using Headers

Portkey Authentication

Portkey API Key

Provider Authentication

1. Provider Slug + Auth

2. Virtual Key

3. Config

4. Custom Host

Additional Portkey Headers

Trace ID

Metadata

Cache Force Refresh

Cache Namespace

Request Timeout

Custom Headers

Forward Headers

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

Azure

Google Vertex AI

AWS Bedrock

List of All Headers

Using Headers