Available on all Portkey plans.
Creating Configs
Navigate to the ‘Configs’ page in the Portkey app and click ‘Create’ to start writing a new config.
Using Configs
Configs are supported across all integrations.
- Through the config parameter of the Portkey SDK client(Directly or via frameworks)
- Through the config headers in the OpenAI SDK
- Via the REST API through the
x-portkey-config header
Applying Gateway Configs
Gateway configs allow you to unlock the gateway superpowers of Portkey. You can create a config in the UI and attach it’s config id in the OpenAI client.
NodeJS
Python
OpenAI NodeJS
OpenAI Python
cURL
const portkey = new Portkey({
apiKey: "PORTKEY_API_KEY",
config: "pc-***" // Supports a string config id or a config object
});
portkey = Portkey(
api_key="PORTKEY_API_KEY",
config="pc-***" # Supports a string config id or a config object
)
const openai = new OpenAI({
apiKey: 'OPENAI_API_KEY', // defaults to process.env["OPENAI_API_KEY"],
baseURL: PORTKEY_GATEWAY_URL,
defaultHeaders: createHeaders({
provider: "openai",
apiKey: "PORTKEY_API_KEY", // defaults to process.env["PORTKEY_API_KEY"]
config: "CONFIG_ID" // Fetched from the UI
})
});
client = OpenAI(
api_key="OPENAI_API_KEY", # defaults to os.environ.get("OPENAI_API_KEY")
base_url=PORTKEY_GATEWAY_URL,
default_headers=createHeaders(
provider="openai",
api_key="PORTKEY_API_KEY", # defaults to os.environ.get("PORTKEY_API_KEY")
config="CONFIG_ID"
)
)
curl https://api.portkey.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "x-portkey-api-key: $PORTKEY_API_KEY" \
-H "x-portkey-provider: openai" \
-H "x-portkey-config: $CONFIG_ID" \
-d '{
"model": "gpt-3.5-turbo",
"messages": [{
"role": "user",
"content": "Hello!"
}]
}'
Note: If you have a default configuration set in the client, but also include a configuration in a specific request, the request-specific configuration will take precedence and replace the default config for that particular request.
NodeJS
Python
OpenAI NodeJS
OpenAI Python
portkey.chat.completions.create({
messages: [{role: "user", content: "Say this is a test"}],
model: "gpt-3.5-turbo"
}, {config: "pc-***"})
portkey.with_options(config="pc-***").chat.completions.create(
messages = [{ "role": 'user', "content": 'Say this is a test' }],
model = 'gpt-3.5-turbo'
})
let reqHeaders = createHeaders({config: "CONFIG_ID});
openai.chat.completions.create({
messages: [{role: "user", content: "Say this is a test"}],
model: "gpt-3.5-turbo"
}, {headers: reqHeaders})
reqHeaders = createHeaders(config="CONFIG_ID")
client.with_options(headers=reqHeaders).chat.completions.create(
messages = [{ "role": 'user', "content": 'Say this is a test' }],
model = 'gpt-3.5-turbo'
})
You can also add the config JSON as a string instead of the slug.
Setting Default Configs on API Keys
You can attach a default config directly to an API key, which means all requests made with that key will automatically use the specified config without needing to include it in each request. This is particularly useful for:
- Integrations that don’t support custom headers (like Open WebUI, LibreChat, and other OpenAI-compatible interfaces)
- Enforcing organization-wide governance policies without requiring code changes
- Centralized configuration management where all applications using a specific API key share the same routing, fallbacks, and caching rules
When you attach a default config to an API key, every request made with that key automatically applies the config’s settings (routing, fallbacks, caching, etc.), even if the application doesn’t send the x-portkey-config header.
To set a default config on an API key:
- Navigate to API Keys in the Portkey dashboard
- Create a new API key or edit an existing one
- In the API key settings, select a config from the Default Config dropdown
- Save the API key
See the Default Configs documentation for detailed instructions and use cases.
If you specify a config in a request (via headers or SDK parameters), it will override the default config for that specific request. The default config only applies when no config is specified in the request itself.
Configs in Logs
Portkey shows your Config usage smartly on the logs page with the Status column and gives you a snapshot of the Gateway activity for every request. Read more about the status column here.
You can also see the ID of the specific Config used for a request separately in the log details, and jump into viewing/editing it directly from the log details page.
Config Object Documentation
Find detailed info about the Config object schema, and more examples:
