Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

feat: Update sdk for SaaS env handling (#1364)

Mike Fortmancb9d35e5b027
diff --git a/sdks/python/openrag_sdk/client.py b/sdks/python/openrag_sdk/client.py
index 2f5cf4dc1..e5a0672ee 100644
--- a/sdks/python/openrag_sdk/client.py
+++ b/sdks/python/openrag_sdk/client.py
@@ -37,9 +37,7 @@ class ModelsClient:
"""
from .models import ModelsResponse
- response = await self._client._request(
- "GET", f"/api/v1/models/{provider}"
- )
+ response = await self._client._request("GET", f"/api/v1/models/{provider}")
data = response.json()
return ModelsResponse(**data)
@@ -116,6 +114,7 @@ class OpenRAGClient:
self,
api_key: str | None = None,
*,
+ extra_headers: dict[str, str] | None = None,
base_url: str | None = None,
timeout: float = 30.0,
http_client: httpx.AsyncClient | None = None,
@@ -125,22 +124,26 @@ class OpenRAGClient:
Args:
api_key: API key for authentication. Falls back to OPENRAG_API_KEY env var.
+ Optional when using IBM auth — pass credentials via extra_headers instead.
+ extra_headers: Additional headers forwarded on every request. Used in IBM
+ auth mode to pass X-Username and X-Api-Key from the user's MCP config.
base_url: Base URL for the API. Falls back to OPENRAG_URL env var, then default.
timeout: Request timeout in seconds (default 30).
http_client: Optional custom httpx.AsyncClient instance.
"""
# Resolve API key from argument or environment
self._api_key = api_key or os.environ.get("OPENRAG_API_KEY")
- if not self._api_key:
+ self._extra_headers: dict[str, str] = extra_headers or {}
+ if not (self._api_key or self._extra_headers):
raise AuthenticationError(
- "API key is required. Set OPENRAG_API_KEY environment variable or pass api_key argument."
+ "API key or extra headers are required.",
+ "Set OPENRAG_API_KEY environment variable or,"
+ "pass api_key or extra_headers argument.",
)
# Resolve base URL from argument or environment
self._base_url = (
- base_url
- or os.environ.get("OPENRAG_URL")
- or self.DEFAULT_BASE_URL
+ base_url or os.environ.get("OPENRAG_URL") or self.DEFAULT_BASE_URL
).rstrip("/")
self._timeout = timeout
@@ -163,10 +166,13 @@ class OpenRAGClient:
@property
def _headers(self) -> dict[str, str]:
"""Get request headers with authentication."""
- return {
- "X-API-Key": self._api_key,
+ headers: dict[str, str] = {
"Content-Type": "application/json",
+ **self._extra_headers,
}
+ if self._api_key:
+ headers["X-API-Key"] = self._api_key
+ return headers
async def _request(
self,
diff --git a/sdks/python/pyproject.toml b/sdks/python/pyproject.toml
index 27322f766..0ef8e94ce 100644
--- a/sdks/python/pyproject.toml
+++ b/sdks/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "openrag-sdk"
-version = "0.2.2"
+version = "0.3.0rc1"
description = "Official Python SDK for OpenRAG API"
readme = "README.md"
license = "MIT"
diff --git a/sdks/python/uv.lock b/sdks/python/uv.lock
index 5c7180210..672af33dd 100644
--- a/sdks/python/uv.lock
+++ b/sdks/python/uv.lock
@@ -121,7 +121,7 @@ wheels = [
[[package]]
name = "openrag-sdk"
-version = "0.2.2"
+version = "0.3.0rc1"
source = { editable = "." }
dependencies = [
{ name = "httpx" },
diff --git a/sdks/typescript/package.json b/sdks/typescript/package.json
index 262c8ae8f..14555a2a7 100644
--- a/sdks/typescript/package.json
+++ b/sdks/typescript/package.json
@@ -1,6 +1,6 @@
{
"name": "openrag-sdk",
- "version": "0.2.2",
+ "version": "0.3.0rc1",
"description": "Official TypeScript/JavaScript SDK for OpenRAG API",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
diff --git a/sdks/typescript/src/client.ts b/sdks/typescript/src/client.ts
index c6080d39a..698d74767 100644
--- a/sdks/typescript/src/client.ts
+++ b/sdks/typescript/src/client.ts
@@ -91,7 +91,8 @@ interface RequestOptions {
export class OpenRAGClient {
private static readonly DEFAULT_BASE_URL = "http://localhost:3000";
- private readonly _apiKey: string;
+ private readonly _apiKey: string | undefined;
+ private readonly _extraHeaders: Record<string, string>;
private readonly _baseUrl: string;
private readonly _timeout: number;
@@ -108,12 +109,8 @@ export class OpenRAGClient {
constructor(options: OpenRAGClientOptions = {}) {
// Resolve API key from argument or environment
- this._apiKey = options.apiKey || getEnv("OPENRAG_API_KEY") || "";
- if (!this._apiKey) {
- throw new AuthenticationError(
- "API key is required. Set OPENRAG_API_KEY environment variable or pass apiKey option."
- );
- }
+ this._apiKey = options.apiKey || getEnv("OPENRAG_API_KEY") || undefined;
+ this._extraHeaders = options.extraHeaders ?? {};
// Resolve base URL from argument or environment
this._baseUrl = (
@@ -134,9 +131,11 @@ export class OpenRAGClient {
/** @internal Get request headers with authentication. */
_getHeaders(isMultipart = false): Record<string, string> {
- const headers: Record<string, string> = {
- "X-API-Key": this._apiKey,
- };
+ const headers: Record<string, string> = { ...this._extraHeaders };
+
+ if (this._apiKey) {
+ headers["X-API-Key"] = this._apiKey;
+ }
if (!isMultipart) {
headers["Content-Type"] = "application/json";
diff --git a/sdks/typescript/src/types.ts b/sdks/typescript/src/types.ts
index f1ca0723c..395f0a36a 100644
--- a/sdks/typescript/src/types.ts
+++ b/sdks/typescript/src/types.ts
@@ -230,8 +230,12 @@ export interface DeleteKnowledgeFilterResponse {
// Client options
export interface OpenRAGClientOptions {
- /** API key for authentication. Falls back to OPENRAG_API_KEY env var. */
+ /** API key for authentication. Falls back to OPENRAG_API_KEY env var.
+ * Optional when using IBM auth — pass credentials via extraHeaders instead. */
apiKey?: string;
+ /** Additional headers forwarded on every request. Used in IBM auth mode
+ * to pass X-Username and X-Api-Key from the user's MCP config. */
+ extraHeaders?: Record<string, string>;
/** Base URL for the API. Falls back to OPENRAG_URL env var. */
baseUrl?: string;
/** Request timeout in milliseconds (default 30000). */
diff --git a/tests/integration/sdk/test_auth.py b/tests/integration/sdk/test_auth.py
index af233dbca..851209f76 100644
--- a/tests/integration/sdk/test_auth.py
+++ b/tests/integration/sdk/test_auth.py
@@ -15,16 +15,65 @@ pytestmark = pytest.mark.skipif(
class TestAuth:
"""Test authentication and API key behaviour."""
- def test_missing_api_key_raises_at_construction(self):
- """Client must raise AuthenticationError immediately if no api_key is given."""
+ def test_missing_api_key_and_extra_headers_raises_at_construction(self):
+ """Client must raise AuthenticationError immediately when neither api_key
+ nor extra_headers are supplied (and no OPENRAG_API_KEY env var is set)."""
from openrag_sdk import OpenRAGClient
from openrag_sdk.exceptions import AuthenticationError
env_backup = os.environ.pop("OPENRAG_API_KEY", None)
try:
- with pytest.raises(AuthenticationError):
+ with pytest.raises(AuthenticationError) as exc_info:
OpenRAGClient()
+ assert "API key or extra headers are required" in str(exc_info.value)
+ finally:
+ if env_backup is not None:
+ os.environ["OPENRAG_API_KEY"] = env_backup
+
+ def test_extra_headers_alone_satisfies_auth_check(self):
+ """Client must not raise when extra_headers are provided without an api_key.
+
+ This covers the IBM auth mode where X-Username / X-Api-Key are passed via
+ extra_headers instead of the OPENRAG_API_KEY env var or api_key argument.
+ """
+ from openrag_sdk import OpenRAGClient
+
+ env_backup = os.environ.pop("OPENRAG_API_KEY", None)
+ try:
+ client = OpenRAGClient(
+ extra_headers={"X-Username": "testuser", "X-Api-Key": "ibm-key"},
+ base_url=_base_url,
+ )
+ assert client is not None
+ finally:
+ if env_backup is not None:
+ os.environ["OPENRAG_API_KEY"] = env_backup
+
+ def test_env_var_api_key_satisfies_auth_check(self):
+ """Client must not raise when only the OPENRAG_API_KEY env var is set."""
+ from openrag_sdk import OpenRAGClient
+
+ env_backup = os.environ.pop("OPENRAG_API_KEY", None)
+ try:
+ os.environ["OPENRAG_API_KEY"] = "orag_env_var_key"
+ client = OpenRAGClient(base_url=_base_url)
+ assert client is not None
+ finally:
+ del os.environ["OPENRAG_API_KEY"]
+ if env_backup is not None:
+ os.environ["OPENRAG_API_KEY"] = env_backup
+
+ def test_explicit_api_key_takes_precedence_over_env_var(self):
+ """Explicit api_key argument overrides the OPENRAG_API_KEY env var."""
+ from openrag_sdk import OpenRAGClient
+
+ env_backup = os.environ.pop("OPENRAG_API_KEY", None)
+ try:
+ os.environ["OPENRAG_API_KEY"] = "orag_env_var_key"
+ client = OpenRAGClient(api_key="orag_explicit_key", base_url=_base_url)
+ assert client._api_key == "orag_explicit_key"
finally:
+ del os.environ["OPENRAG_API_KEY"]
if env_backup is not None:
os.environ["OPENRAG_API_KEY"] = env_backup