Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: send custom headers on remote connections (#15097)

Sourav Rajvi14b016639f69
diff --git a/studio/backend/core/inference/external_provider.py b/studio/backend/core/inference/external_provider.py
index f26c4f38d2b..4363b33970d 100644
--- a/studio/backend/core/inference/external_provider.py
+++ b/studio/backend/core/inference/external_provider.py
@@ -34,7 +34,9 @@ from core.inference.openai_responses_shared import (
)
from core.inference.sse_control_frames import sanitize_provider_sse_line
from models.providers import (
+ normalize_provider_extra_headers,
normalize_provider_reasoning_config,
+ render_provider_extra_headers,
validate_provider_reasoning_contract,
)
@@ -1547,6 +1549,7 @@ class ExternalProviderClient:
*,
api_type: str = "chat_completions",
reasoning_config: Optional[dict] = None,
+ extra_headers: Optional[dict] = None,
managed_loopback: bool = False,
):
self.provider_type = provider_type
@@ -1556,6 +1559,8 @@ class ExternalProviderClient:
if provider_type == "custom"
else None
)
+ self.extra_headers = normalize_provider_extra_headers(extra_headers)
+ self._header_vars: dict[str, str] = {}
validate_provider_reasoning_contract(provider_type, self.api_type, self.reasoning_config)
from core.inference.providers import validate_provider_base_url
@@ -1581,6 +1586,26 @@ class ExternalProviderClient:
# same guaranteed 400 on every provider turn.
self._responses_compaction_rejected = False
+ def set_header_context(self, thread_id: Optional[str], model: Optional[str]) -> None:
+ """Values for ``{{VAR}}`` in extra headers; set before any request of a chat turn."""
+ session = (thread_id or "").strip()
+ self._header_vars = {
+ "CHAT_SESSION_ID": session,
+ "THREAD_ID": session,
+ "MODEL": model or "",
+ "PROVIDER_TYPE": self.provider_type,
+ }
+
+ def _credential_digest(self) -> str:
+ """Served-metadata cache identity: the key, plus the headers this request really sends."""
+ material = self.api_key or ""
+ headers = render_provider_extra_headers(
+ getattr(self, "extra_headers", None), getattr(self, "_header_vars", None)
+ )
+ if headers:
+ material = _json.dumps([material, headers], sort_keys = True)
+ return hashlib.sha256(material.encode()).hexdigest()
+
def _auth_headers(self) -> dict[str, str]:
"""Build authentication headers using the provider's registry config."""
from core.inference.providers import get_provider_info
@@ -1619,6 +1644,14 @@ class ExternalProviderClient:
headers[auth_header] = f"{auth_prefix}{self.api_key}"
# Merge provider-specific extra headers (anthropic-version, OpenRouter attribution).
headers.update(provider_info.get("extra_headers", {}))
+ custom = render_provider_extra_headers(
+ getattr(self, "extra_headers", {}), getattr(self, "_header_vars", {})
+ )
+ if custom:
+ # Header names are case-insensitive: an override replaces, never duplicates.
+ overridden = {name.lower() for name in custom}
+ headers = {k: v for k, v in headers.items() if k.lower() not in overridden}
+ headers.update(custom)
return headers
def _chat_headers(self, thread_id: Optional[str]) -> dict[str, str]:
@@ -1680,6 +1713,7 @@ class ExternalProviderClient:
compaction_fallback: Optional[CompactionFallback] = None,
) -> AsyncGenerator[str, None]:
"""tool_choice none disables all tools so they cannot bill or leak; top_k and penalties are opt-in."""
+ self.set_header_context(thread_id, model)
tool_choice_disabled = (
isinstance(tool_choice, str) and tool_choice.strip().lower() == "none"
)
@@ -7496,7 +7530,7 @@ class ExternalProviderClient:
if self.provider_type != "vllm":
return False
now = time.monotonic()
- key = (self.base_url, hashlib.sha256((self.api_key or "").encode()).hexdigest())
+ key = (self.base_url, self._credential_digest())
cached = _served_versions.get(key)
if cached is not None and cached[0] > now:
return cached[1]
@@ -7525,7 +7559,7 @@ class ExternalProviderClient:
if self.provider_type not in _SERVED_WINDOW_PROVIDERS:
return None
now = time.monotonic()
- key = (self.base_url, hashlib.sha256((self.api_key or "").encode()).hexdigest(), model)
+ key = (self.base_url, self._credential_digest(), model)
cached = _served_windows.get(key)
if cached is not None and cached[0] > now:
return cached[1]
@@ -7551,7 +7585,7 @@ class ExternalProviderClient:
if self.provider_type != "llama_cpp":
return None
now = time.monotonic()
- key = (self.base_url, hashlib.sha256((self.api_key or "").encode()).hexdigest(), model)
+ key = (self.base_url, self._credential_digest(), model)
cached = _served_templates.get(key)
if cached is not None and cached[0] > now:
return cached[1]
diff --git a/studio/backend/models/inference.py b/studio/backend/models/inference.py
index 037195e572e..9bc7cc97aee 100644
--- a/studio/backend/models/inference.py
+++ b/studio/backend/models/inference.py
@@ -36,7 +36,7 @@ from core.inference.runtime_context import MAX_REQUESTABLE_CONTEXT
from utils.upload_limits import VIDEO_INPUT_REFERENCE_JSON_MAX_BYTES
from core.inference.video_families import MAX_VIDEO_NUM_FRAMES
from picker.schemas import MAX_CHAT_TEMPLATE_BYTES
-from models.providers import ProviderReasoningConfig
+from models.providers import ProviderReasoningConfig, normalize_provider_extra_headers
from utils.reasoning_budget import validate_reasoning_budget_message
# A 24 MB reference audio as a base64 data URL, with room for its header.
@@ -3272,6 +3272,22 @@ class ChatCompletionRequest(BaseModel):
None,
description = "[x-unsloth] Override base URL for the external provider.",
)
+ extra_headers: Optional[dict[str, str]] = Field(
+ None,
+ description = (
+ "[x-unsloth] Extra request headers when the request carries an API key. "
+ "Saved connections send these from the stored record instead, so an "
+ "explicit key cannot bind saved metadata."
+ ),
+ )
+
+ @field_validator("extra_headers", mode = "before")
+ @classmethod
+ def _validate_chat_extra_headers(cls, value: Any) -> Any:
+ if value is None:
+ return None
+ return normalize_provider_extra_headers(value)
+
enable_prompt_caching: Optional[Union[bool, str]] = Field(
None,
description = (
diff --git a/studio/backend/models/providers.py b/studio/backend/models/providers.py
index c55fc6103cc..b363dec01bd 100644
--- a/studio/backend/models/providers.py
+++ b/studio/backend/models/providers.py
@@ -3,9 +3,13 @@
"""Pydantic schemas for the external LLM providers API."""
+from __future__ import annotations
+
+import re
from typing import Literal, Optional
+from urllib.parse import quote
-from pydantic import BaseModel, ConfigDict, Field, StrictBool, ValidationError
+from pydantic import BaseModel, ConfigDict, Field, StrictBool, ValidationError, field_validator
ProviderApiType = Literal["chat_completions", "responses", "systemone"]
@@ -42,6 +46,78 @@ def validate_provider_reasoning_contract(provider_type: str, api_type: str, conf
MAX_JSON_SAFE_INTEGER = 9_007_199_254_740_991
+_MAX_EXTRA_HEADERS = 16
+_MAX_HEADER_NAME = 64
+_MAX_HEADER_VALUE = 1024
+_HEADER_NAME_RE = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
+# httpx encodes header values as ASCII; anything else fails every request to the connection.
+_HEADER_VALUE_RE = re.compile(r"^[\t\x20-\x7e]*$")
+_HEADER_SAFE_CHARS = "".join(chr(c) for c in range(0x20, 0x7F) if chr(c) != "%")
+_HEADER_TEMPLATE_RE = re.compile(r"\{\{\s*([A-Z][A-Z0-9_]*)\s*\}\}")
+_FORBIDDEN_EXTRA_HEADERS = frozenset(
+ {
+ "authorization",
+ "proxy-authorization",
+ "cookie",
+ "set-cookie",
+ "host",
+ "content-length",
+ "content-type",
+ "connection",
+ "transfer-encoding",
+ "te",
+ "trailer",
+ "upgrade",
+ "keep-alive",
+ "api-key",
+ "x-api-key",
+ "x-goog-api-key",
+ }
+)
+
+
+def normalize_provider_extra_headers(value) -> dict[str, str]:
+ """Validate a connection's extra headers. Empty or absent becomes {}."""
+ if value is None:
+ return {}
+ if not isinstance(value, dict):
+ raise ValueError("extra_headers must be an object of header name to value.")
+ if len(value) > _MAX_EXTRA_HEADERS:
+ raise ValueError(f"At most {_MAX_EXTRA_HEADERS} extra headers are allowed.")
+ headers: dict[str, str] = {}
+ for raw_name, raw_value in value.items():
+ if not isinstance(raw_name, str) or not isinstance(raw_value, str):
+ raise ValueError("extra_headers keys and values must be strings.")
+ name = raw_name.strip()
+ if not name or len(name) > _MAX_HEADER_NAME or not _HEADER_NAME_RE.fullmatch(name):
+ raise ValueError(f"Invalid extra header name: {raw_name!r}.")
+ if name.lower() in _FORBIDDEN_EXTRA_HEADERS:
+ raise ValueError(f"Cannot set reserved header {name!r}.")
+ if not _HEADER_VALUE_RE.fullmatch(raw_value):
+ raise ValueError(f"Header {name!r} must be printable ASCII on one line.")
+ if len(raw_value) > _MAX_HEADER_VALUE:
+ raise ValueError(f"Header {name!r} is too long.")
+ # h11 refuses a value with surrounding whitespace.
+ headers[name] = raw_value.strip(" \t")
+ return headers
+
+
+def render_provider_extra_headers(
+ headers: dict[str, str] | None, variables: dict[str, str] | None = None
+) -> dict[str, str]:
+ """Replace ``{{ VAR }}`` placeholders. Unknown names become empty strings."""
+ if not headers:
+ return {}
+ values = variables or {}
+
+ def replace(match: re.Match[str]) -> str:
+ # Substituted ids and model names are arbitrary text; percent-encode what httpx cannot send.
+ return quote(values.get(match.group(1), ""), safe = _HEADER_SAFE_CHARS)
+
+ return {
+ name: _HEADER_TEMPLATE_RE.sub(replace, value).strip(" \t")
+ for name, value in headers.items()
+ }
class ProviderRegistryEntry(BaseModel):
@@ -82,7 +158,21 @@ class ProviderRegistryEntry(BaseModel):
)
-class ProviderCreate(BaseModel):
+class ExtraHeadersMixin(BaseModel):
+ extra_headers: Optional[dict[str, str]] = Field(
+ default = None,
+ description = "Optional request headers. Values may include {{CHAT_SESSION_ID}}.",
+ )
+
+ @field_validator("extra_headers", mode = "before")
+ @classmethod
+ def _validate_extra_headers(cls, value):
+ if value is None:
+ return None
+ return normalize_provider_extra_headers(value)
+
+
+class ProviderCreate(ExtraHeadersMixin):
"""Request to create a saved provider configuration."""
api_type: ProviderApiType = "chat_completions"
@@ -120,7 +210,7 @@ class ProviderCreate(BaseModel):
)
-class ProviderUpdate(BaseModel):
+class ProviderUpdate(ExtraHeadersMixin):
"""Request to update a saved provider configuration."""
api_type: Optional[ProviderApiType] = None
@@ -194,6 +284,10 @@ class ProviderResponse(BaseModel):
None,
description = "Configured maximum Max Tokens cap for this connection",
)
+ extra_headers: dict[str, str] = Field(
+ default_factory = dict,
+ description = "Optional request headers. Values may include {{CHAT_SESSION_ID}}.",
+ )
shared: bool = Field(False, description = "Whether every account on this installation can use it")
shared_by_owner: bool = Field(
False,
@@ -236,7 +330,7 @@ class ModelCatalogResponse(BaseModel):
providers: dict[str, dict[str, dict]]
-class ProviderModelsRequest(BaseModel):
+class ProviderModelsRequest(ExtraHeadersMixin):
"""Request to list models from an external provider."""
api_type: ProviderApiType = "chat_completions"
@@ -255,7 +349,7 @@ class ProviderModelsRequest(BaseModel):
)
-class ProviderTestRequest(BaseModel):
+class ProviderTestRequest(ExtraHeadersMixin):
"""Request to test connectivity to an external provider."""
api_type: ProviderApiType = "chat_completions"
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 86d867c306f..ab87d7db58e 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -3604,6 +3604,18 @@ def _request_is_saved_credential_workflow(request: Any) -> bool:
# A UI session, the Deep Research key, or the key `unsloth start` minted for the owner's coding
# agents. Every other API key, keyless caller and data-recipe key still gets nothing.
+def _saved_extra_headers(row: Optional[dict], request: Any) -> dict:
+ """A saved row's headers, under the same API-key gate as its saved key."""
+ if not row or _request_has_api_key(request):
+ return {}
+ return row.get("extra_headers") or {}
+
+
+def _saved_extra_headers_kwarg(row: Optional[dict], request: Any) -> dict:
+ headers = _saved_extra_headers(row, request)
+ return {"extra_headers": headers} if headers else {}
+
+
def _request_may_use_saved_provider_key(request: Any) -> bool:
if not _request_has_api_key(request) or _request_is_saved_credential_workflow(request):
return True
@@ -24463,6 +24475,7 @@ async def _external_tts_speech(body: AudioSpeechRequest, request: Request) -> Re
provider_type = config["provider_type"],
base_url = base_url,
api_key = api_key,
+ **_saved_extra_headers_kwarg(current, request),
)
# FastAPI does not cancel non-streaming handlers on disconnect; paid synthesis would continue.
speech_task = asyncio.create_task(
@@ -24746,6 +24759,7 @@ async def _external_stt_transcription(
provider_type = config["provider_type"],
base_url = base_url,
api_key = api_key,
+ **_saved_extra_headers_kwarg(current, request),
)
transcription_task = asyncio.create_task(
client.create_transcription(
@@ -28535,6 +28549,7 @@ async def _proxy_to_external_provider(
base_url = payload.provider_base_url
api_type = payload.provider_api_type
reasoning_config = normalize_provider_reasoning_config(payload.provider_reasoning_config)
+ extra_headers: Optional[dict] = None
saved_provider_snapshot: Optional[dict] = None
if managed is not None:
@@ -28566,6 +28581,11 @@ async def _proxy_to_external_provider(
base_url = config["base_url"]
api_type = config.get("api_type", "chat_completions")
reasoning_config = normalize_provider_reasoning_config(config.get("reasoning_config"))
+ extra_headers = config.get("extra_headers")
+
+ # An explicit key keeps the edited target: headers come from the request, not the saved row.
+ if managed is None and payload.encrypted_api_key:
+ extra_headers = payload.extra_headers
if not provider_type:
raise HTTPException(
@@ -29081,12 +29101,16 @@ async def _proxy_to_external_provider(
account_access.require_connection_model_allowed(
current, payload.external_model or payload.model
)
+ may_use_saved = _request_may_use_saved_provider_key(request)
api_key = await asyncio.to_thread(
resolve_provider_api_key_or_400,
payload.provider_id,
payload.encrypted_api_key,
- allow_saved_key = _request_may_use_saved_provider_key(request),
+ allow_saved_key = may_use_saved,
)
+ if not payload.encrypted_api_key:
+ # Saved headers can carry credentials: same gate as the saved key.
+ extra_headers = current.get("extra_headers") if may_use_saved else None
else:
api_key = resolve_provider_api_key_or_400(
payload.provider_id,
@@ -29145,8 +29169,12 @@ async def _proxy_to_external_provider(
api_key = api_key,
api_type = api_type,
**({"reasoning_config": reasoning_config} if reasoning_config is not None else {}),
+ **({"extra_headers": extra_headers} if extra_headers else {}),
**({"managed_loopback": True} if managed is not None else {}),
)
+ # Metadata preflights (served context window, template) run before streaming starts.
+ if extra_headers:
+ client.set_header_context(payload.thread_id, model)
_non_stream_custom_responses = (
provider_type == "custom" and api_type == "responses" and payload.stream is False
)
@@ -29998,7 +30026,9 @@ def _resolve_openai_cloud_client(
) -> ExternalProviderClient:
"""Needs an OpenAI cloud base URL (shell tool exists only there); runs on the loop for one snapshot."""
base_url = body.provider_base_url or get_base_url("openai")
- if body.provider_id and not body.encrypted_api_key:
+ config: dict = {}
+ saved_config = bool(body.provider_id and not body.encrypted_api_key)
+ if saved_config:
config = providers_db.get_provider(body.provider_id)
if config is None:
raise HTTPException(
@@ -30041,10 +30071,13 @@ def _resolve_openai_cloud_client(
)
if not api_key:
raise HTTPException(status_code = 400, detail = "No OpenAI API key is saved.")
+ # Same project / organization scope as chat on this connection.
+ headers = config.get("extra_headers") if saved_config and allow_saved_key else None
return ExternalProviderClient(
provider_type = "openai",
base_url = base_url,
api_key = api_key,
+ **({"extra_headers": headers} if headers else {}),
)
@@ -49138,6 +49171,7 @@ async def _external_image_generation(
provider_type = config["provider_type"],
base_url = base_url,
api_key = api_key,
+ **_saved_extra_headers_kwarg(current, request),
timeout = 600.0,
)
owner = current_account_id()
diff --git a/studio/backend/routes/providers.py b/studio/backend/routes/providers.py
index 46b5553c729..cfac166b826 100644
--- a/studio/backend/routes/providers.py
+++ b/studio/backend/routes/providers.py
@@ -63,6 +63,7 @@ from models.providers import (
ProviderTestRequest,
ProviderTestResult,
ProviderUpdate,
+ normalize_provider_extra_headers,
validate_provider_reasoning_contract,
)
from storage import credential_secrets, providers_db
@@ -143,7 +144,21 @@ def _log_provider_failure(event: str, exc: Exception, **fields) -> None:
_SHARED_READ_ONLY = "This connection is shared by the installation owner. Only they can change it."
-def _provider_response(row: dict) -> ProviderResponse:
+def _request_extra_headers(payload, via_api_key: bool) -> dict[str, str]:
+ if "extra_headers" in getattr(payload, "model_fields_set", set()):
+ return normalize_provider_extra_headers(payload.extra_headers)
+ provider_id = getattr(payload, "provider_id", None)
+ # Saved headers can carry credentials: same gate as the saved key.
+ if not provider_id or payload.encrypted_api_key or via_api_key:
+ return {}
+ row = providers_db.get_provider(provider_id)
+ # Saved headers go only to the saved endpoint, like the saved key.
+ if not row or (payload.base_url or None) != (row.get("base_url") or None):
+ return {}
+ return normalize_provider_extra_headers(row.get("extra_headers"))
+
+
+def _provider_response(row: dict, *, hide_headers: bool = False) -> ProviderResponse:
has_api_key = credential_secrets.provider_api_key_saved(row["id"])
return ProviderResponse(
id = row["id"],
@@ -152,6 +167,12 @@ def _provider_response(row: dict) -> ProviderResponse:
base_url = row["base_url"],
api_type = row.get("api_type", "chat_completions"),
reasoning_config = row.get("reasoning_config"),
+ # Header values can carry credentials; other accounts and API keys never read them.
+ extra_headers = (
+ {}
+ if hide_headers or row.get("shared_by_owner")
+ else normalize_provider_extra_headers(row.get("extra_headers"))
+ ),
is_enabled = bool(row["is_enabled"]),
has_api_key = has_api_key,
auth_kind = ("chatgpt_oauth" if row["provider_type"] == "openai_codex" else "api_key"),
@@ -298,10 +319,13 @@ async def get_pricing_snapshot(current_subject: str = Depends(get_current_subjec
# FastAPI offloads sync reads; mutations stay on-loop to preserve atomic sequences.
@router.get("/", response_model = list[ProviderResponse])
-def list_provider_configs(_current_subject: str = Depends(get_current_subject)):
+def list_provider_configs(
+ _current_subject: str = Depends(get_current_subject),
+ via_api_key: bool = Depends(authenticated_via_api_key),
+):
"""List all saved provider configurations."""
rows = providers_db.list_providers()
- return [_provider_response(row) for row in rows]
+ return [_provider_response(row, hide_headers = via_api_key) for row in rows]
@router.post("/", response_model = ProviderResponse, status_code = 201)
@@ -368,6 +392,7 @@ async def create_provider_config(
max_output_tokens = payload.max_output_tokens,
api_type = payload.api_type,
reasoning_config = payload.reasoning_config,
+ extra_headers = payload.extra_headers,
shared = payload.shared,
)
try:
@@ -472,6 +497,7 @@ async def update_provider_config(
"max_output_tokens",
"api_type",
"reasoning_config",
+ "extra_headers",
"shared",
}
metadata_requested = bool(payload.model_fields_set & metadata_fields)
@@ -513,6 +539,8 @@ async def update_provider_config(
if payload.reasoning_config is not None
else None
)
+ if "extra_headers" in payload.model_fields_set:
+ metadata_updates["extra_headers"] = payload.extra_headers or {}
# The row snapshot this request found, keyed the way update_provider takes it.
_restorable = dict(
@@ -524,6 +552,7 @@ async def update_provider_config(
max_output_tokens = existing.get("max_output_tokens"),
api_type = existing.get("api_type", "chat_completions"),
reasoning_config = existing.get("reasoning_config"),
+ extra_headers = existing.get("extra_headers") or {},
shared = bool(existing.get("shared")),
)
@@ -545,7 +574,11 @@ async def update_provider_config(
if field == "id":
continue
# Explicit null clears nullable overrides; elsewhere it means "not sent".
- if written is None and field not in {"max_output_tokens", "reasoning_config"}:
+ if written is None and field not in {
+ "max_output_tokens",
+ "reasoning_config",
+ "extra_headers",
+ }:
continue
if not _current_matches(current, field, written):
continue
@@ -976,6 +1009,7 @@ async def test_provider(
base_url = base_url,
api_key = api_key,
api_type = payload.api_type,
+ extra_headers = _request_extra_headers(payload, via_api_key),
timeout = _PROVIDER_CONNECTIVITY_TIMEOUT_SECONDS,
)
@@ -1157,7 +1191,10 @@ async def _list_model_capabilities(payload: ProviderModelsRequest, via_api_key:
raise HTTPException(status_code = 400, detail = str(exc)) from None
# Per credential: one key's model list is not another caller's.
- key_digest = hashlib.sha256((api_key or "").encode("utf-8")).hexdigest()[:16]
+ extra_headers = _request_extra_headers(payload, via_api_key)
+ key_digest = hashlib.sha256(
+ json.dumps([api_key or "", extra_headers], sort_keys = True).encode("utf-8")
+ ).hexdigest()[:16]
cache_key = f"{payload.provider_type}\n{base_url}\n{key_digest}"
cached = _model_capability_cache.get(cache_key)
if cached is not None and time.monotonic() - cached[0] < _MODEL_CAPABILITY_CACHE_TTL_SECONDS:
@@ -1169,6 +1206,7 @@ async def _list_model_capabilities(payload: ProviderModelsRequest, via_api_key:
base_url = base_url,
api_key = api_key,
api_type = payload.api_type,
+ extra_headers = extra_headers,
timeout = 15.0,
)
try:
@@ -1255,6 +1293,7 @@ async def list_provider_models(
base_url = base_url,
api_key = api_key,
api_type = payload.api_type,
+ extra_headers = _request_extra_headers(payload, via_api_key),
timeout = 15.0,
)
diff --git a/studio/backend/routes/systemone.py b/studio/backend/routes/systemone.py
index 5e481671b15..aa795aef175 100644
--- a/studio/backend/routes/systemone.py
+++ b/studio/backend/routes/systemone.py
@@ -364,7 +364,13 @@ async def _connection_decide(
except ValueError as exc:
raise _error(503, "api_usage_error", str(exc)) from None
api_key = await arun_as(OWNER, _connection_key(provider_id, config))
- client = ExternalProviderClient(config["provider_type"], base_url, api_key)
+ headers = config.get("extra_headers")
+ client = ExternalProviderClient(
+ config["provider_type"],
+ base_url,
+ api_key,
+ **({"extra_headers": headers} if headers else {}),
+ )
try:
result = await client.create_decision(connection.model, state, questions)
except httpx.HTTPStatusError as exc:
@@ -381,7 +387,7 @@ async def _connection_decide(
async def _connection_key(provider_id: str, config: dict) -> str:
- routing_fields = ("provider_type", "base_url", "api_type", "is_enabled")
+ routing_fields = ("provider_type", "base_url", "api_type", "is_enabled", "extra_headers")
async with provider_config_guard(provider_id):
current = await asyncio.to_thread(providers_db.get_provider, provider_id)
if current is None or any(current.get(f) != config.get(f) for f in routing_fields):
@@ -416,7 +422,13 @@ async def refresh_listed_decision_models() -> None:
None,
prefer_saved_key = True,
)
- client = ExternalProviderClient(row["provider_type"], row["base_url"], api_key, 10.0)
+ client = ExternalProviderClient(
+ row["provider_type"],
+ row["base_url"],
+ api_key,
+ 10.0,
+ **({"extra_headers": row["extra_headers"]} if row.get("extra_headers") else {}),
+ )
models = await arun_as(OWNER, client.list_decision_models())
except Exception:
models = []
diff --git a/studio/backend/storage/providers_db.py b/studio/backend/storage/providers_db.py
index 02d66ede406..91de70dec35 100644
--- a/studio/backend/storage/providers_db.py
+++ b/studio/backend/storage/providers_db.py
@@ -18,7 +18,11 @@ from urllib.parse import urlparse
logger = logging.getLogger(__name__)
-from models.providers import ProviderReasoningConfig, normalize_provider_reasoning_config
+from models.providers import (
+ ProviderReasoningConfig,
+ normalize_provider_extra_headers,
+ normalize_provider_reasoning_config,
+)
from storage.studio_db import connect_studio_db
from utils.paths import studio_db_path, ensure_dir
@@ -100,6 +104,22 @@ def _decode_reasoning_config(raw) -> Optional[dict]:
return None
+def _encode_extra_headers(headers) -> Optional[str]:
+ normalized = normalize_provider_extra_headers(headers)
+ if not normalized:
+ return None
+ return json.dumps(normalized)
+
+
+def _decode_extra_headers(raw) -> dict[str, str]:
+ if not raw:
+ return {}
+ try:
+ return normalize_provider_extra_headers(json.loads(raw))
+ except (json.JSONDecodeError, TypeError, ValueError):
+ return {}
+
+
def _row_models(row: sqlite3.Row) -> tuple[list[str], list[str]]:
return (
_decode_models_json(row["models_json"] if "models_json" in row.keys() else None),
@@ -141,6 +161,8 @@ def _ensure_schema(conn: sqlite3.Connection) -> None:
conn.execute("ALTER TABLE llm_providers ADD COLUMN max_output_tokens INTEGER")
if "reasoning_config_json" not in existing_cols:
conn.execute("ALTER TABLE llm_providers ADD COLUMN reasoning_config_json TEXT")
+ if "extra_headers_json" not in existing_cols:
+ conn.execute("ALTER TABLE llm_providers ADD COLUMN extra_headers_json TEXT")
if "shared" not in existing_cols:
conn.execute("ALTER TABLE llm_providers ADD COLUMN shared INTEGER NOT NULL DEFAULT 0")
# ALTER TABLE persists independently in SQLite, but its one-time data migration does not.
@@ -201,10 +223,12 @@ def create_provider(
max_output_tokens: Optional[int] = None,
api_type: str = "chat_completions",
reasoning_config: Optional[dict] = None,
+ extra_headers: Optional[dict] = None,
shared: bool = False,
) -> None:
"""Insert a new provider configuration."""
reasoning_json = _encode_reasoning_config(reasoning_config)
+ extra_headers_json = _encode_extra_headers(extra_headers)
now = datetime.now(timezone.utc).isoformat()
conn = get_connection()
try:
@@ -213,9 +237,9 @@ def create_provider(
INSERT INTO llm_providers (
id, provider_type, display_name, base_url,
models_json, available_models_json, max_output_tokens, api_type,
- reasoning_config_json, shared, created_at, updated_at
+ reasoning_config_json, extra_headers_json, shared, created_at, updated_at
)
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""",
(
id,
@@ -227,6 +251,7 @@ def create_provider(
max_output_tokens,
api_type,
reasoning_json,
+ extra_headers_json,
1 if shared else 0,
now,
now,
@@ -249,6 +274,7 @@ def update_provider(
connection: sqlite3.Connection | None = None,
api_type: str | None = None,
reasoning_config: dict | None | object = _UNSET,
+ extra_headers: dict | None | object = _UNSET,
shared: bool | None = None,
) -> bool:
"""Update fields on an existing provider. Returns True if a row was updated."""
@@ -278,6 +304,9 @@ def update_provider(
if reasoning_config is not _UNSET:
updates.append("reasoning_config_json = ?")
params.append(_encode_reasoning_config(reasoning_config))
+ if extra_headers is not _UNSET:
+ updates.append("extra_headers_json = ?")
+ params.append(_encode_extra_headers(extra_headers))
if shared is not None:
updates.append("shared = ?")
params.append(1 if shared else 0)
@@ -316,6 +345,7 @@ def delete_provider(id: str) -> bool:
def _row_to_provider(row: sqlite3.Row) -> dict:
data = dict(row)
data["reasoning_config"] = _decode_reasoning_config(data.pop("reasoning_config_json", None))
+ data["extra_headers"] = _decode_extra_headers(data.pop("extra_headers_json", None))
models, available_models = _row_models(row)
data["models"] = models
data["available_models"] = available_models
diff --git a/studio/backend/tests/test_account_shared_connections.py b/studio/backend/tests/test_account_shared_connections.py
index 2ab94fbc137..c062d5973db 100644
--- a/studio/backend/tests/test_account_shared_connections.py
+++ b/studio/backend/tests/test_account_shared_connections.py
@@ -434,3 +434,125 @@ def test_checking_a_shared_connection_probes_no_model_and_quotes_no_upstream_err
"message": "Connection failed. Ask the owner to check this connection.",
"models_count": None,
}
+
+
+def header_upstream():
+ seen = []
+
+ class Handler(http.server.BaseHTTPRequestHandler):
+ def do_GET(self):
+ seen.append(self.headers.get("X-Gateway-Token"))
+ body = json.dumps({"data": [{"id": model} for model in UPSTREAM_MODELS]}).encode()
+ self.send_response(200)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(body)))
+ self.end_headers()
+ self.wfile.write(body)
+
+ def log_message(self, *args):
+ pass
+
+ server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ threading.Thread(target = server.serve_forever, daemon = True).start()
+ try:
+ yield f"http://127.0.0.1:{server.server_address[1]}/v1", seen
+ finally:
+ server.shutdown()
+ server.server_close()
+
+
+def test_shared_extra_headers_stay_with_the_saved_endpoint(monkeypatch, header_upstream):
+ base_url, seen = header_upstream
+ provider_id = owner_connection("https://api.example.com/v1")
+ run_as(
+ OWNER,
+ providers_db.update_provider,
+ provider_id,
+ extra_headers = {"X-Gateway-Token": "owner-header-secret"},
+ )
+ mpu.set_managed_private_provider_urls_allowed(True)
+ [row] = listed(ALICE)
+ assert "owner-header-secret" not in json.dumps(row)
+ [owner_row] = listed(OWNER)
+ assert owner_row["extra_headers"] == {"X-Gateway-Token": "owner-header-secret"}
+
+ monkeypatch.setattr(providers, "resolve_provider_api_key_or_400", lambda *a, **k: "alice-key")
+ with client_for(ALICE) as client:
+ response = client.post(
+ "/providers/models",
+ json = {
+ "provider_type": "custom",
+ "provider_id": provider_id,
+ "encrypted_api_key": "alice-encrypted",
+ "base_url": base_url,
+ },
+ )
+ assert response.status_code == 200, response.text
+ assert seen == [None]
+
+
+def api_key_client_for(account):
+ client = client_for(account)
+ client.app.dependency_overrides[authenticated_via_api_key] = lambda: True
+ return client
+
+
+def test_api_key_callers_neither_read_nor_spend_saved_headers(monkeypatch, header_upstream):
+ base_url, seen = header_upstream
+ mpu.set_managed_private_provider_urls_allowed(True)
+ with client_for(OWNER) as client:
+ created = client.post(
+ "/providers/",
+ json = {
+ "provider_type": "custom",
+ "display_name": "Header Gateway",
+ "base_url": base_url,
+ "models": UPSTREAM_MODELS[:1],
+ "extra_headers": {"X-Gateway-Token": "owner-header-secret"},
+ },
+ )
+ assert created.status_code == 201, created.text
+ provider_id = created.json()["id"]
+ with api_key_client_for(OWNER) as client:
+ [row] = client.get("/providers/").json()
+ assert "owner-header-secret" not in json.dumps(row)
+ response = client.post(
+ "/providers/models", json = {"provider_type": "custom", "provider_id": provider_id}
+ )
+ assert response.status_code == 200, response.text
+ with client_for(OWNER) as client:
+ response = client.post(
+ "/providers/models", json = {"provider_type": "custom", "provider_id": provider_id}
+ )
+ assert response.status_code == 200, response.text
+ assert seen == [None, "owner-header-secret"]
+
+
+def test_capability_cache_is_keyed_by_headers(monkeypatch):
+ calls = []
+
+ class FakeClient:
+ def __init__(self, **kwargs):
+ calls.append(kwargs["extra_headers"])
+
+ async def list_models(self):
+ return [{"id": "m"}]
+
+ async def close(self):
+ pass
+
+ monkeypatch.setattr(providers, "ExternalProviderClient", FakeClient)
+ monkeypatch.setattr(providers, "resolve_provider_api_key_or_400", lambda *a, **k: "shared-key")
+ monkeypatch.setattr(providers, "validate_provider_base_url", lambda url: url)
+ providers._model_capability_cache.clear()
+ from models.providers import ProviderModelsRequest
+
+ for tenant in ("a", "b", "a"):
+ payload = ProviderModelsRequest(
+ provider_type = "openrouter",
+ base_url = "https://gw.example/v1",
+ extra_headers = {"X-Tenant": tenant},
+ )
+ asyncio.run(providers._list_model_capabilities(payload, False))
+ assert calls == [{"X-Tenant": "a"}, {"X-Tenant": "b"}]
diff --git a/studio/backend/tests/test_provider_extra_headers.py b/studio/backend/tests/test_provider_extra_headers.py
new file mode 100644
index 00000000000..02568023f8b
--- /dev/null
+++ b/studio/backend/tests/test_provider_extra_headers.py
@@ -0,0 +1,339 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Saved connection extra headers, including {{CHAT_SESSION_ID}} interpolation."""
+
+import asyncio
+import json
+from http.server import BaseHTTPRequestHandler
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from pydantic import ValidationError
+
+from core.inference import external_provider as ep
+from models.providers import (
+ ProviderCreate,
+ ProviderUpdate,
+ normalize_provider_extra_headers,
+ render_provider_extra_headers,
+)
+from storage import providers_db
+from .test_external_provider_sampling_over_the_wire import _Server
+
+
+HEADERS = {"X-LiteLLM-Session-Id": "unsloth-{{CHAT_SESSION_ID}}", "X-Title": "Unsloth"}
+
+
+class Handler(BaseHTTPRequestHandler):
+ def log_message(self, *args):
+ pass
+
+ def do_POST(self): # noqa: N802
+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+ self.server.recorded.append(
+ {
+ "path": self.path,
+ "body": body,
+ "session": self.headers.get("X-LiteLLM-Session-Id"),
+ "title": self.headers.get("X-Title"),
+ "authorization": self.headers.get("Authorization"),
+ }
+ )
+ data = b'data: {"choices":[{"index":0,"delta":{"content":"ok"}}]}\n\ndata: [DONE]\n\n'
+ self.send_response(200)
+ self.send_header("Content-Type", "text/event-stream")
+ self.send_header("Content-Length", str(len(data)))
+ self.end_headers()
+ self.wfile.write(data)
+
+
+def test_reserved_headers_are_rejected():
+ with pytest.raises(ValueError, match = "reserved"):
+ normalize_provider_extra_headers({"Authorization": "Bearer secret"})
+ with pytest.raises(ValidationError):
+ ProviderCreate(
+ provider_type = "custom",
+ display_name = "Gateway",
+ extra_headers = {"Authorization": "Bearer secret"},
+ )
+
+
+def test_header_values_must_be_sendable():
+ for value in ("Ünsloth", "a\nb", "a\x00b"):
+ with pytest.raises(ValueError, match = "printable ASCII"):
+ normalize_provider_extra_headers({"X-Title": value})
+ assert normalize_provider_extra_headers({"X-Title": "a\tb c"}) == {"X-Title": "a\tb c"}
+
+
+def test_template_interpolation():
+ rendered = render_provider_extra_headers(
+ HEADERS, {"CHAT_SESSION_ID": "thread-1", "MODEL": "gpt"}
+ )
+ assert rendered["X-LiteLLM-Session-Id"] == "unsloth-thread-1"
+ assert rendered["X-Title"] == "Unsloth"
+
+
+def test_extra_headers_persist_and_reach_the_wire(tmp_path, monkeypatch):
+ monkeypatch.setattr(providers_db, "studio_db_path", lambda: tmp_path / "studio.db")
+ providers_db.reset_schema_state_for_tests()
+ payload = ProviderCreate(
+ provider_type = "custom",
+ display_name = "LiteLLM",
+ base_url = "https://gateway.example/v1",
+ extra_headers = HEADERS,
+ )
+ providers_db.create_provider(id = "litellm", **payload.model_dump(exclude = {"encrypted_api_key"}))
+ row = providers_db.get_provider("litellm")
+ assert row["extra_headers"] == HEADERS
+ assert providers_db.update_provider("litellm", extra_headers = {"X-Title": "Studio"})
+ assert providers_db.get_provider("litellm")["extra_headers"] == {"X-Title": "Studio"}
+ assert ProviderUpdate(extra_headers = None).extra_headers is None
+
+ with _Server(Handler) as server:
+
+ async def send():
+ async with httpx.AsyncClient(trust_env = False) as transport:
+ monkeypatch.setattr(ep, "_http_client", transport)
+ client = ep.ExternalProviderClient(
+ "custom",
+ server.base_url,
+ "sk-test",
+ extra_headers = HEADERS,
+ )
+ output = client.stream_chat_completion(
+ messages = [{"role": "user", "content": "hi"}],
+ model = "proxy-model",
+ thread_id = "chat-42",
+ )
+ assert "ok" in "".join([line async for line in output])
+ await client.close()
+
+ asyncio.run(send())
+ recorded = server.bodies[-1]
+ assert recorded["session"] == "unsloth-chat-42"
+ assert recorded["title"] == "Unsloth"
+ assert recorded["authorization"] == "Bearer sk-test"
+
+
+def _drive(coro):
+ return asyncio.new_event_loop().run_until_complete(coro)
+
+
+def test_explicit_key_sends_request_headers_without_saved_lookup(monkeypatch):
+ from models.inference import ChatCompletionRequest
+ from routes import inference as inf_mod
+
+ class ClientReached(Exception):
+ pass
+
+ monkeypatch.setattr(
+ inf_mod.providers_db,
+ "get_provider",
+ lambda _provider_id: (_ for _ in ()).throw(
+ AssertionError("explicit keys must not bind saved metadata")
+ ),
+ )
+ monkeypatch.setattr(
+ inf_mod,
+ "resolve_provider_api_key_or_400",
+ lambda *_args, **_kwargs: "replacement-key",
+ )
+
+ def client(**kwargs):
+ raise ClientReached(kwargs)
+
+ monkeypatch.setattr(inf_mod, "ExternalProviderClient", client)
+ payload = ChatCompletionRequest(
+ messages = [{"role": "user", "content": "hello"}],
+ provider_id = "provider-1",
+ provider_type = "custom",
+ provider_base_url = "https://new.example/v1",
+ encrypted_api_key = "encrypted-replacement",
+ extra_headers = HEADERS,
+ external_model = "new-model",
+ )
+ request = SimpleNamespace(headers = {}, state = SimpleNamespace(skip_api_monitor = True))
+ with pytest.raises(ClientReached) as reached:
+ _drive(inf_mod._proxy_to_external_provider(payload, request))
+ assert reached.value.args[0] == {
+ "provider_type": "custom",
+ "base_url": "https://new.example/v1",
+ "api_key": "replacement-key",
+ "api_type": "chat_completions",
+ "extra_headers": HEADERS,
+ }
+
+
+def test_chat_request_rejects_reserved_extra_headers():
+ from models.inference import ChatCompletionRequest
+ with pytest.raises(ValidationError, match = "reserved"):
+ ChatCompletionRequest(
+ messages = [{"role": "user", "content": "hello"}],
+ extra_headers = {"Authorization": "Bearer secret"},
+ )
+
+
[email protected]("may_use_saved", [True, False])
+def test_saved_headers_follow_the_saved_key_gate(monkeypatch, may_use_saved):
+ from models.inference import ChatCompletionRequest
+ from routes import inference as inf_mod
+
+ class ClientReached(Exception):
+ pass
+
+ row = {
+ "id": "provider-1",
+ "provider_type": "custom",
+ "display_name": "Gateway",
+ "base_url": "https://gw.example/v1",
+ "api_type": "chat_completions",
+ "is_enabled": True,
+ "reasoning_config": None,
+ "extra_headers": {"X-Gateway-Token": "saved-secret"},
+ }
+ monkeypatch.setattr(inf_mod.providers_db, "get_provider", lambda _pid: dict(row))
+ monkeypatch.setattr(inf_mod, "_request_may_use_saved_provider_key", lambda _r: may_use_saved)
+ monkeypatch.setattr(inf_mod, "resolve_provider_api_key_or_400", lambda *a, **k: None)
+
+ def client(**kwargs):
+ raise ClientReached(kwargs)
+
+ monkeypatch.setattr(inf_mod, "ExternalProviderClient", client)
+ payload = ChatCompletionRequest(
+ messages = [{"role": "user", "content": "hello"}],
+ provider_id = "provider-1",
+ external_model = "m",
+ )
+ request = SimpleNamespace(headers = {}, state = SimpleNamespace(skip_api_monitor = True))
+ with pytest.raises(ClientReached) as reached:
+ _drive(inf_mod._proxy_to_external_provider(payload, request))
+ sent = reached.value.args[0].get("extra_headers")
+ assert sent == ({"X-Gateway-Token": "saved-secret"} if may_use_saved else None)
+
+
+def test_saved_extra_headers_helper_honours_api_keys(monkeypatch):
+ from routes import inference as inf_mod
+
+ row = {"extra_headers": {"X-Gateway-Token": "saved-secret"}}
+ monkeypatch.setattr(inf_mod, "_request_has_api_key", lambda _r: False)
+ assert inf_mod._saved_extra_headers(row, object()) == row["extra_headers"]
+ monkeypatch.setattr(inf_mod, "_request_has_api_key", lambda _r: True)
+ assert inf_mod._saved_extra_headers(row, object()) == {}
+
+
+def test_values_are_trimmed_and_substitutions_stay_sendable():
+ assert normalize_provider_extra_headers({"X-Token": " secret "}) == {"X-Token": "secret"}
+ rendered = render_provider_extra_headers(
+ {"X-Session": "unsloth-{{CHAT_SESSION_ID}}", "X-Model": "{{MODEL}} "},
+ {"CHAT_SESSION_ID": "会話-1\r\n", "MODEL": ""},
+ )
+ assert rendered == {"X-Session": "unsloth-%E4%BC%9A%E8%A9%B1-1%0D%0A", "X-Model": ""}
+ httpx.Request("GET", "http://x", headers = rendered)
+
+
[email protected]("allow_saved_key", [True, False])
+def test_container_client_keeps_the_connection_scope(monkeypatch, allow_saved_key):
+ from models.inference import OpenAIContainerRequest
+ from routes import inference as inf_mod
+
+ row = {
+ "id": "openai-1",
+ "provider_type": "openai",
+ "display_name": "OpenAI",
+ "base_url": "https://api.openai.com/v1",
+ "is_enabled": True,
+ "extra_headers": {"OpenAI-Project": "proj_123"},
+ }
+ monkeypatch.setattr(inf_mod.providers_db, "get_provider", lambda _pid: dict(row))
+ monkeypatch.setattr(inf_mod, "resolve_provider_api_key_or_400", lambda *a, **k: "sk-test")
+ captured = {}
+ monkeypatch.setattr(inf_mod, "ExternalProviderClient", lambda **kw: captured.update(kw))
+ inf_mod._resolve_openai_cloud_client(
+ OpenAIContainerRequest(provider_id = "openai-1"), allow_saved_key = allow_saved_key
+ )
+ assert captured.get("extra_headers") == (
+ {"OpenAI-Project": "proj_123"} if allow_saved_key else None
+ )
+
+
+def test_served_metadata_cache_identity_includes_headers():
+ import hashlib
+
+ plain = ep.ExternalProviderClient("custom", "https://gw.example/v1", "sk")
+ assert plain._credential_digest() == hashlib.sha256(b"sk").hexdigest()
+ a = ep.ExternalProviderClient(
+ "custom", "https://gw.example/v1", "sk", extra_headers = {"X-Tenant": "a"}
+ )
+ b = ep.ExternalProviderClient(
+ "custom", "https://gw.example/v1", "sk", extra_headers = {"X-Tenant": "b"}
+ )
+ assert len({plain._credential_digest(), a._credential_digest(), b._credential_digest()}) == 3
+ routed = ep.ExternalProviderClient(
+ "custom", "https://gw.example/v1", "sk", extra_headers = {"X-Route": "{{CHAT_SESSION_ID}}"}
+ )
+ routed.set_header_context("chat-1", "m")
+ first = routed._credential_digest()
+ routed.set_header_context("chat-2", "m")
+ assert routed._credential_digest() != first
+
+
+def test_extra_headers_replace_registry_headers_case_insensitively():
+ client = ep.ExternalProviderClient(
+ "openrouter", "https://openrouter.ai/api/v1", "sk", extra_headers = {"x-title": "My App"}
+ )
+ headers = client._auth_headers()
+ assert [k for k in headers if k.lower() == "x-title"] == ["x-title"]
+ assert headers["x-title"] == "My App"
+
+
+def test_route_sets_header_context_before_any_upstream_call(monkeypatch):
+ from models.inference import ChatCompletionRequest
+ from routes import inference as inf_mod
+
+ class ContextSet(Exception):
+ pass
+
+ class FakeClient:
+ def __init__(self, **kwargs):
+ self.kwargs = kwargs
+
+ def set_header_context(self, thread_id, model):
+ raise ContextSet(thread_id, model)
+
+ monkeypatch.setattr(inf_mod, "resolve_provider_api_key_or_400", lambda *a, **k: "key")
+ monkeypatch.setattr(inf_mod, "ExternalProviderClient", FakeClient)
+ payload = ChatCompletionRequest(
+ messages = [{"role": "user", "content": "hello"}],
+ provider_type = "custom",
+ provider_base_url = "https://gw.example/v1",
+ encrypted_api_key = "encrypted",
+ extra_headers = HEADERS,
+ external_model = "m",
+ thread_id = "chat-7",
+ )
+ request = SimpleNamespace(headers = {}, state = SimpleNamespace(skip_api_monitor = True))
+ with pytest.raises(ContextSet) as reached:
+ _drive(inf_mod._proxy_to_external_provider(payload, request))
+ assert reached.value.args == ("chat-7", "m")
+
+
+def test_decision_key_refuses_headers_changed_mid_start(monkeypatch):
+ from fastapi import HTTPException
+ from routes import systemone
+
+ row = {
+ "provider_type": "custom",
+ "base_url": "https://gw.example/v1",
+ "api_type": "systemone",
+ "is_enabled": True,
+ "extra_headers": {"X-Gateway-Token": "new"},
+ }
+ monkeypatch.setattr(systemone.providers_db, "get_provider", lambda _pid: dict(row))
+ monkeypatch.setattr(systemone, "resolve_provider_api_key_or_400", lambda *a, **k: "new-key")
+ stale = {**row, "extra_headers": {"X-Gateway-Token": "old"}}
+ with pytest.raises(HTTPException) as refused:
+ _drive(systemone._connection_key("p", stale))
+ assert refused.value.status_code == 409
+ assert _drive(systemone._connection_key("p", dict(row))) == "new-key"
diff --git a/studio/frontend/src/features/chat/api/providers-api.ts b/studio/frontend/src/features/chat/api/providers-api.ts
index 44c04c38d99..8146888506f 100644
--- a/studio/frontend/src/features/chat/api/providers-api.ts
+++ b/studio/frontend/src/features/chat/api/providers-api.ts
@@ -55,6 +55,7 @@ export interface ProviderConfig {
available_models?: string[];
max_output_tokens?: number | null;
reasoning_config?: CustomReasoningConfig | null;
+ extra_headers?: Record<string, string>;
shared?: boolean;
shared_by_owner?: boolean;
created_at: string;
@@ -225,6 +226,7 @@ export async function createProviderConfig(payload: {
availableModels?: string[];
maxOutputTokens?: number | null;
reasoningConfig?: CustomReasoningConfig | null;
+ extraHeaders?: Record<string, string>;
shared?: boolean;
apiKey?: string;
}): Promise<ProviderConfig> {
@@ -245,6 +247,9 @@ export async function createProviderConfig(payload: {
...(payload.reasoningConfig === undefined
? {}
: { reasoning_config: payload.reasoningConfig }),
+ ...(payload.extraHeaders === undefined
+ ? {}
+ : { extra_headers: payload.extraHeaders }),
...(payload.shared === undefined ? {} : { shared: payload.shared }),
encrypted_api_key: encryptedApiKey,
}),
@@ -278,6 +283,7 @@ export async function updateProviderConfig(
availableModels?: string[];
maxOutputTokens?: number | null;
reasoningConfig?: CustomReasoningConfig | null;
+ extraHeaders?: Record<string, string>;
shared?: boolean;
apiKey?: string;
clearApiKey?: boolean;
@@ -302,6 +308,9 @@ export async function updateProviderConfig(
...(payload.reasoningConfig === undefined
? {}
: { reasoning_config: payload.reasoningConfig }),
+ ...(payload.extraHeaders === undefined
+ ? {}
+ : { extra_headers: payload.extraHeaders }),
...(payload.shared === undefined ? {} : { shared: payload.shared }),
...(payload.apiKey === undefined ? {} : { encrypted_api_key: encryptedApiKey }),
...(payload.clearApiKey === undefined ? {} : { clear_api_key: payload.clearApiKey }),
@@ -354,6 +363,7 @@ export async function testProviderConnection(payload: {
apiKey: string;
baseUrl?: string | null;
apiType?: ConnectionApiType;
+ extraHeaders?: Record<string, string>;
modelId?: string | null;
}): Promise<ProviderTestResult> {
return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
@@ -367,6 +377,9 @@ export async function testProviderConnection(payload: {
encrypted_api_key: encryptedApiKey,
base_url: payload.baseUrl ?? null,
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
+ ...(payload.extraHeaders === undefined
+ ? {}
+ : { extra_headers: payload.extraHeaders }),
model_id: payload.modelId ?? null,
}),
});
@@ -381,6 +394,7 @@ export async function listProviderModels(payload: {
apiKey: string;
baseUrl?: string | null;
apiType?: ConnectionApiType;
+ extraHeaders?: Record<string, string>;
}): Promise<ProviderModelInfo[]> {
return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
const response = await authFetch("/api/providers/models", {
@@ -393,6 +407,9 @@ export async function listProviderModels(payload: {
encrypted_api_key: encryptedApiKey,
base_url: payload.baseUrl ?? null,
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
+ ...(payload.extraHeaders === undefined
+ ? {}
+ : { extra_headers: payload.extraHeaders }),
}),
});
return parseJsonOrThrow<ProviderModelInfo[]>(response);
diff --git a/studio/frontend/src/features/chat/chat-providers-dialog.tsx b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
index 00d0935c717..f645948b613 100644
--- a/studio/frontend/src/features/chat/chat-providers-dialog.tsx
+++ b/studio/frontend/src/features/chat/chat-providers-dialog.tsx
@@ -115,6 +115,7 @@ import {
refreshProviderModelCatalogs,
syncExternalProvidersFromBackend,
} from "./sync-external-providers";
+import { extraHeadersToDraft, parseExtraHeadersDraft } from "./extra-headers";
const PROVIDER_FORM_EASE: [number, number, number, number] = [
0.165, 0.84, 0.44, 1,
@@ -299,6 +300,7 @@ export function ChatProvidersSettings({
const [baseUrlDraft, setBaseUrlDraft] = useState("");
const [apiType, setApiType] = useState<ConnectionApiType>("chat_completions");
const [maxOutputTokensDraft, setMaxOutputTokensDraft] = useState("");
+ const [extraHeadersDraft, setExtraHeadersDraft] = useState("");
const [editingBackendProviderType, setEditingBackendProviderType] = useState<
string | null
>(null);
@@ -529,6 +531,7 @@ export function ChatProvidersSettings({
if (seededProviderTypeRef.current === providerType) return;
seededProviderTypeRef.current = providerType;
setMaxOutputTokensDraft("");
+ setExtraHeadersDraft("");
setApiType("chat_completions");
setReasoningConfig(null);
setEditingBackendProviderType(null);
@@ -644,6 +647,7 @@ export function ChatProvidersSettings({
setShowApiKey(false);
setBaseUrlDraft("");
setMaxOutputTokensDraft("");
+ setExtraHeadersDraft("");
setApiType("chat_completions");
setReasoningConfig(null);
setEditingBackendProviderType(null);
@@ -819,6 +823,7 @@ export function ChatProvidersSettings({
apiKey: silent ? "" : apiKey.trim(),
baseUrl,
apiType: providerType === LEGACY_CUSTOM_PROVIDER_TYPE ? apiType : undefined,
+ extraHeaders: parseExtraHeadersDraft(extraHeadersDraft),
});
if (silent && autoLoadedCatalogRef.current !== autoLoad) return;
// The picker keeps only ids, so per-model capabilities are learned here or lost.
@@ -1001,6 +1006,7 @@ export function ChatProvidersSettings({
const maxOutputTokens = supportsMaxOutputTokens
? parseMaxOutputTokens(maxOutputTokensDraft)
: undefined;
+ const extraHeaders = parseExtraHeadersDraft(extraHeadersDraft);
const created = await createProviderConfig({
providerType: backendProviderType,
displayName,
@@ -1014,6 +1020,7 @@ export function ChatProvidersSettings({
reasoningConfig: isCustomReasoningConnection
? (showCustomReasoning ? reasoningConfig : null)
: undefined,
+ extraHeaders,
...(showShareToggle && sharedDraft ? { shared: true } : {}),
apiKey: apiKey.trim(),
@@ -1039,6 +1046,7 @@ export function ChatProvidersSettings({
? []
: pruneProviderModelIds(providerType, availableModels),
maxOutputTokens: created.max_output_tokens ?? undefined,
+ extraHeaders: created.extra_headers ?? extraHeaders,
reasoningConfig: created.provider_type === "custom"
? normalizeCustomReasoningConfig(created.reasoning_config)
: undefined,
@@ -1180,6 +1188,7 @@ export function ChatProvidersSettings({
const maxOutputTokens = supportsMaxOutputTokens
? parseMaxOutputTokens(maxOutputTokensDraft)
: undefined;
+ const extraHeaders = parseExtraHeadersDraft(extraHeadersDraft);
const updated = await updateProviderConfig(editingProviderId, {
displayName: isEditingCustomProvider
? customProviderName.trim() ||
@@ -1193,6 +1202,7 @@ export function ChatProvidersSettings({
reasoningConfig: isCustomReasoningConnection
? (showCustomReasoning ? reasoningConfig : null)
: undefined,
+ extraHeaders,
...(showShareToggle && sharedDraft !== (existing.shared === true)
? { shared: sharedDraft }
: {}),
@@ -1225,6 +1235,7 @@ export function ChatProvidersSettings({
? (updated.available_models?.length ? updated.available_models : existing.availableModels)
: availableModelsToSave,
maxOutputTokens: updated.max_output_tokens ?? undefined,
+ extraHeaders: updated.extra_headers ?? extraHeaders,
reasoningConfig: updated.provider_type === "custom"
? normalizeCustomReasoningConfig(updated.reasoning_config)
: undefined,
@@ -1359,6 +1370,7 @@ export function ChatProvidersSettings({
getExternalMinOutputTokens(provider.providerType),
).toString(),
);
+ setExtraHeadersDraft(extraHeadersToDraft(provider.extraHeaders));
setEditingBackendProviderType(provider.backendProviderType ?? null);
setModelSearchQuery("");
setIsReasoningModel(
@@ -1518,6 +1530,7 @@ export function ChatProvidersSettings({
apiKey: savedKey,
baseUrl: provider.baseUrl || null,
apiType: provider.decisionsOnly ? "systemone" : provider.apiType,
+ extraHeaders: provider.extraHeaders,
modelId:
provider.providerType === LEGACY_CUSTOM_PROVIDER_TYPE ||
isDecisionConnection(provider)
@@ -1870,6 +1883,36 @@ export function ChatProvidersSettings({
</div>
) : null}
+ {providerType !== "openai_codex" ? (
+ <div className="grid grid-cols-[minmax(140px,0.8fr)_minmax(0,1.2fr)] items-start gap-4 px-4 py-3 @max-[520px]:grid-cols-1">
+ <div className="flex min-w-0 flex-col gap-0.5">
+ <Label
+ htmlFor="provider-extra-headers"
+ className="text-sm font-medium"
+ >
+ Extra headers
+ </Label>
+ <p
+ id="provider-extra-headers-help"
+ className="text-xs leading-snug text-muted-foreground"
+ >
+ One header per line, as Name: value. Use {"{{CHAT_SESSION_ID}}"} for
+ the open chat. Sent on every request to this connection.
+ </p>
+ </div>
+ <Textarea
+ id="provider-extra-headers"
+ value={extraHeadersDraft}
+ onChange={(event) => setExtraHeadersDraft(event.target.value)}
+ placeholder={
+ 'X-LiteLLM-Session-Id: unsloth-{{CHAT_SESSION_ID}}'
+ }
+ aria-describedby="provider-extra-headers-help"
+ className="min-h-20 font-mono text-sm"
+ />
+ </div>
+ ) : null}
+
{providerType === "llama_cpp" ? (
<div className="flex items-start justify-between gap-4 px-4 py-3">
<div className="space-y-1">
diff --git a/studio/frontend/src/features/chat/external-providers.ts b/studio/frontend/src/features/chat/external-providers.ts
index ede1749ae08..a4c11b79a5e 100644
--- a/studio/frontend/src/features/chat/external-providers.ts
+++ b/studio/frontend/src/features/chat/external-providers.ts
@@ -26,6 +26,7 @@ export interface ExternalProviderConfig {
/** The type as the backend stores it (may differ from providerType). Absent means unknown. */
backendProviderType?: string;
maxOutputTokens?: number;
+ extraHeaders?: Record<string, string>;
hasApiKey?: boolean;
shared?: boolean;
@@ -364,6 +365,18 @@ export function normalizeProviderMaxOutputTokens(
return value;
}
+/** Copy saved headers into chat state. Validation lives in extra-headers.ts, loaded with Connections. */
+export function extraHeadersFromSaved(
+ value: unknown,
+): Record<string, string> | undefined {
+ if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+ const headers: Record<string, string> = {};
+ for (const [name, headerValue] of Object.entries(value as Record<string, unknown>)) {
+ if (name && typeof headerValue === "string") headers[name] = headerValue;
+ }
+ return Object.keys(headers).length ? headers : undefined;
+}
+
/** All types except ChatGPT subscriptions; both stored and UI types are checked. */
export function supportsProviderMaxOutputTokens(
uiProviderType: string | null | undefined,
@@ -614,6 +627,7 @@ function normalizeProvider(raw: ExternalProviderConfig): ExternalProviderConfig
? raw.backendProviderType.trim()
: undefined,
maxOutputTokens: normalizeProviderMaxOutputTokens(raw.maxOutputTokens),
+ extraHeaders: extraHeadersFromSaved(raw.extraHeaders),
enablePromptCaching: supportsProviderPromptCaching(providerType)
? raw.enablePromptCaching !== false
: undefined,
diff --git a/studio/frontend/src/features/chat/extra-headers.ts b/studio/frontend/src/features/chat/extra-headers.ts
new file mode 100644
index 00000000000..47ac5bd4f90
--- /dev/null
+++ b/studio/frontend/src/features/chat/extra-headers.ts
@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+const FORBIDDEN_EXTRA_HEADERS = new Set([
+ "authorization",
+ "proxy-authorization",
+ "cookie",
+ "set-cookie",
+ "host",
+ "content-length",
+ "content-type",
+ "connection",
+ "transfer-encoding",
+ "te",
+ "trailer",
+ "upgrade",
+ "keep-alive",
+ "api-key",
+ "x-api-key",
+ "x-goog-api-key",
+]);
+const HEADER_NAME_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+const HEADER_VALUE_RE = /^[\t\x20-\x7e]*$/;
+const MAX_EXTRA_HEADERS = 16;
+
+export function extraHeadersToDraft(
+ headers: Record<string, string> | undefined,
+): string {
+ return Object.entries(headers ?? {})
+ .map(([name, value]) => `${name}: ${value}`)
+ .join("\n");
+}
+
+export function parseExtraHeadersDraft(draft: string): Record<string, string> {
+ const trimmed = draft.trim();
+ if (!trimmed) return {};
+ const entries: [string, unknown][] = [];
+ if (trimmed.startsWith("{")) {
+ const parsed: unknown = JSON.parse(trimmed);
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+ throw new Error("Extra headers JSON must be an object of header names to string values.");
+ }
+ entries.push(...Object.entries(parsed as Record<string, unknown>));
+ } else {
+ for (const line of trimmed.split("\n")) {
+ const text = line.trim();
+ if (!text || text.startsWith("#")) continue;
+ const separator = text.indexOf(":");
+ if (separator <= 0) {
+ throw new Error(`Invalid extra header line: ${text}`);
+ }
+ entries.push([text.slice(0, separator), text.slice(separator + 1)]);
+ }
+ }
+ const headers: Record<string, string> = {};
+ for (const [rawName, rawValue] of entries) {
+ const name = rawName.trim();
+ if (typeof rawValue !== "string") {
+ throw new Error(`Header ${name} must have a string value.`);
+ }
+ const value = rawValue.trim();
+ if (!HEADER_NAME_RE.test(name)) {
+ throw new Error(`Invalid extra header name: ${name}`);
+ }
+ if (FORBIDDEN_EXTRA_HEADERS.has(name.toLowerCase())) {
+ throw new Error(`Cannot set reserved header ${name}.`);
+ }
+ if (!HEADER_VALUE_RE.test(value)) {
+ throw new Error(`Header ${name} must be printable ASCII.`);
+ }
+ headers[name] = value;
+ }
+ if (Object.keys(headers).length > MAX_EXTRA_HEADERS) {
+ throw new Error(`At most ${MAX_EXTRA_HEADERS} extra headers are allowed.`);
+ }
+ return headers;
+}
diff --git a/studio/frontend/src/features/chat/sync-external-providers.ts b/studio/frontend/src/features/chat/sync-external-providers.ts
index c2f300e52ee..b7cebb50d71 100644
--- a/studio/frontend/src/features/chat/sync-external-providers.ts
+++ b/studio/frontend/src/features/chat/sync-external-providers.ts
@@ -28,6 +28,7 @@ import {
CUSTOM_PROVIDER_PRESETS,
connectionApiFields,
type ExternalProviderConfig,
+ extraHeadersFromSaved,
getExternalProviderApiKey,
isPromptCacheTtl,
LEGACY_CUSTOM_PROVIDER_TYPE,
@@ -302,6 +303,7 @@ export async function syncExternalProvidersFromBackend(
models: resolvedModels,
availableModels: resolvedAvailableModels,
maxOutputTokens: config.max_output_tokens ?? undefined,
+ extraHeaders: extraHeadersFromSaved(config.extra_headers),
reasoningConfig:
config.provider_type === "custom" &&
config.api_type !== "responses" && config.api_type !== "systemone"
diff --git a/studio/frontend/src/features/chat/utils/chat-title.ts b/studio/frontend/src/features/chat/utils/chat-title.ts
index 718eff8bc7f..ef451964cf5 100644
--- a/studio/frontend/src/features/chat/utils/chat-title.ts
+++ b/studio/frontend/src/features/chat/utils/chat-title.ts
@@ -200,6 +200,7 @@ export interface ExternalRoutingFields {
provider_api_type: "chat_completions" | "responses";
provider_reasoning_config?: CustomReasoningConfig;
encrypted_api_key?: string;
+ extra_headers?: Record<string, string>;
}
export type ExternalRoutingUnavailableReason =
@@ -275,6 +276,9 @@ export async function buildExternalRoutingFields(
apiKey,
options.forceRefreshPublicKey ?? false,
),
+ ...(provider.extraHeaders && Object.keys(provider.extraHeaders).length
+ ? { extra_headers: provider.extraHeaders }
+ : {}),
}
: {}),
};
diff --git a/studio/frontend/tests/custom-provider-api-type.test.ts b/studio/frontend/tests/custom-provider-api-type.test.ts
index cf0cec3d01f..3d015273598 100644
--- a/studio/frontend/tests/custom-provider-api-type.test.ts
+++ b/studio/frontend/tests/custom-provider-api-type.test.ts
@@ -34,3 +34,66 @@ test("Responses survives provider requests and cache while legacy cache defaults
providers.saveExternalProviders([config]);
assert.equal(providers.loadExternalProviders()[0].apiType, "chat_completions");
});
+
+test("extra header drafts round-trip and reject reserved names", async () => {
+ const headers = await vite.ssrLoadModule("/src/features/chat/extra-headers.ts");
+ const parsed = headers.parseExtraHeadersDraft(
+ "X-LiteLLM-Session-Id: unsloth-{{CHAT_SESSION_ID}}\nX-Title: Unsloth\n",
+ );
+ assert.equal(parsed["X-LiteLLM-Session-Id"], "unsloth-{{CHAT_SESSION_ID}}");
+ assert.equal(
+ headers.extraHeadersToDraft(parsed),
+ "X-LiteLLM-Session-Id: unsloth-{{CHAT_SESSION_ID}}\nX-Title: Unsloth",
+ );
+ assert.throws(() => headers.parseExtraHeadersDraft("Authorization: Bearer secret"));
+ const json = headers.parseExtraHeadersDraft('{"X-Title":"Studio"}');
+ assert.equal(json["X-Title"], "Studio");
+ assert.throws(() => headers.parseExtraHeadersDraft('{"Authorization":"nope","X-Title":"ok"}'));
+ assert.throws(() => headers.parseExtraHeadersDraft('{"X-Count":1}'));
+ const many = Object.fromEntries(Array.from({ length: 17 }, (_, i) => [`X-H${i}`, "v"]));
+ assert.throws(() => headers.parseExtraHeadersDraft(JSON.stringify(many)), /At most 16/);
+});
+
+test("explicit-key routing sends extra headers; a saved key leaves them on the record", async () => {
+ const routing = await vite.ssrLoadModule("/src/features/chat/utils/chat-title.ts");
+ const extraHeaders = { "X-Title": "Unsloth" };
+ const provider = {
+ id: "gateway",
+ providerType: "custom",
+ name: "Gateway",
+ baseUrl: "https://gateway.example/v1",
+ models: ["proxy-model"],
+ extraHeaders,
+ createdAt: 1,
+ updatedAt: 1,
+ };
+ const saved = await routing.buildExternalRoutingFields({
+ provider,
+ modelId: "proxy-model",
+ apiKey: "",
+ });
+ assert.equal("extra_headers" in saved, false);
+ assert.equal("encrypted_api_key" in saved, false);
+
+ const previous = globalThis.fetch;
+ globalThis.fetch = (async () =>
+ Response.json({
+ public_key: `-----BEGIN PUBLIC KEY-----
+MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1n8QOqkDXkFEOC62kiqZcBCN3
+l/DmD+0BGvjg8h1fFJD2Fla1ibcnmKb9Vok+PmR6jm1JX0yu8JHXPw1om01RwQWe
+nehl2VzGfdEdNaRoKhW5oVsnnfmxlWJ/qWuV2rDK8DK/6UK9sC/duMkRWaRGdhyl
+l+8/fuJc9JDRVzx7HwIDAQAB
+-----END PUBLIC KEY-----`,
+ })) as typeof fetch;
+ try {
+ const explicit = await routing.buildExternalRoutingFields({
+ provider,
+ modelId: "proxy-model",
+ apiKey: "sk-browser-held",
+ });
+ assert.deepEqual(explicit.extra_headers, extraHeaders);
+ assert.equal(typeof explicit.encrypted_api_key, "string");
+ } finally {
+ globalThis.fetch = previous;
+ }
+});