From 66f21b22b4d2cde7cb33d52389908b7267973db3 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Thu, 22 Jan 2026 07:42:52 +0100 Subject: [PATCH 1/3] docs(sdk): note WS header auth to avoid URL secrets --- sdk/arch/agent-server.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx index 8ad7663c..d69b7a6c 100644 --- a/sdk/arch/agent-server.mdx +++ b/sdk/arch/agent-server.mdx @@ -165,6 +165,10 @@ async with websocket_connect(url) as ws: print(event["content"]) ``` +**Authentication note (important)**: +- Avoid putting secrets in URLs. For non-browser clients, prefer sending the session key via headers during the WebSocket handshake (for example `X-Session-API-Key: ` or `Authorization: Bearer `). +- Browser clients typically cannot send custom headers with WebSockets, so query-parameter auth may still be required for browser-based connections. + **Why streaming?** - Real-time feedback to users - Show agent thinking process From 52cfcbe2b48284de34ba0c02ed4322addc45bb06 Mon Sep 17 00:00:00 2001 From: enyst Date: Fri, 23 Jan 2026 10:35:30 +0000 Subject: [PATCH 2/3] docs(sdk): clarify websocket auth headers vs query param precedence --- sdk/arch/agent-server.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx index d69b7a6c..f4924776 100644 --- a/sdk/arch/agent-server.mdx +++ b/sdk/arch/agent-server.mdx @@ -166,8 +166,18 @@ async with websocket_connect(url) as ws: ``` **Authentication note (important)**: -- Avoid putting secrets in URLs. For non-browser clients, prefer sending the session key via headers during the WebSocket handshake (for example `X-Session-API-Key: ` or `Authorization: Bearer `). -- Browser clients typically cannot send custom headers with WebSockets, so query-parameter auth may still be required for browser-based connections. + +The Agent Server accepts WebSocket authentication in two ways: + +- **Recommended (non-browser clients): via headers during the WebSocket handshake** + - `X-Session-API-Key: ` + - `Authorization: Bearer ` +- **Backward compatible (typically browser clients): via query string** + - `?session_api_key=` + +**Precedence**: if `session_api_key` is present in the query string, it overrides any header-based authentication. + +Rationale: avoid putting secrets in URLs when you can (URLs can leak via logs, proxies, etc.). Browsers typically cannot set custom headers on WebSocket connections, so query-parameter auth may be required in browser environments. **Why streaming?** - Real-time feedback to users From 12055bfd773d8e9dd489431c2d77d735dafe8660 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Fri, 23 Jan 2026 11:40:03 +0100 Subject: [PATCH 3/3] Update sdk/arch/agent-server.mdx --- sdk/arch/agent-server.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx index f4924776..7c7e702d 100644 --- a/sdk/arch/agent-server.mdx +++ b/sdk/arch/agent-server.mdx @@ -171,7 +171,6 @@ The Agent Server accepts WebSocket authentication in two ways: - **Recommended (non-browser clients): via headers during the WebSocket handshake** - `X-Session-API-Key: ` - - `Authorization: Bearer ` - **Backward compatible (typically browser clients): via query string** - `?session_api_key=`