diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx
index 8ad7663c..7c7e702d 100644
--- a/sdk/arch/agent-server.mdx
+++ b/sdk/arch/agent-server.mdx
@@ -165,6 +165,19 @@ async with websocket_connect(url) as ws:
             print(event["content"])
 ```
 
+**Authentication note (important)**:
+
+The Agent Server accepts WebSocket authentication in two ways:
+
+- **Recommended (non-browser clients): via headers during the WebSocket handshake**
+  - `X-Session-API-Key: <key>`
+- **Backward compatible (typically browser clients): via query string**
+  - `?session_api_key=<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
 - Show agent thinking process