Portkey API accepts 4 kinds of headers for your requests:

Portkey Authentication HeaderRequiredFor Portkey auth
Provider Authentication Headers OR Cloud-Specific HeadersRequiredFor provider auth
Additional Portkey HeadersOptionalTo pass config, metadata, trace id, cache refresh etc.
Custom HeadersOptionalTo 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

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

​
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)

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

​
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

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.

​
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)

​
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)

​
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)

​
Cache Namespace

​
x-portkey-cache-namespace / cache_namespace / cacheNamespace
string

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

​
Request Timeout

​
x-portkey-request-timeout / request_timeout / requestTimeout
integer

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

​
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)

​
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

For a comprehensive list of all available parameters and their detailed descriptions, please refer to the Portkey SDK Client documentation.

SDK

​
Using Headers in SDKs

You can send these headers through REST API calls as well as by using the OpenAI or Portkey SDKs. With the Portkey SDK, Other than cacheForceRefresh, traceID, and metadata, rest of the headers are passed while instantiating the Portkey client.

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
//  Authorization: "Bearer PROVIDER_API_KEY",
//  provider: "anthropic",
//  customHost: "CUSTOM_URL",
//  forwardHeaders: ["Authorization"],
    virtualKey: "VIRTUAL_KEY",
    config: "CONFIG_ID",
})

const chatCompletion = await portkey.chat.completions.create({
    messages: [{ role: 'user', content: 'Say this is a test' }],
    model: 'gpt-4o',
},{
    traceId: "your_trace_id",
    metadata: {"_user": "432erf6"}
});

console.log(chatCompletion.choices);

Was this page helpful?

AuthenticationSupported Providers