Skip to content

sdk docs: mention WS header auth (avoid URL secrets) #270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

enyst wants to merge 3 commits into OpenHands:main

from enyst:blackcat/oh-tab-h3g-ws-header-auth

Open

sdk docs: mention WS header auth (avoid URL secrets) #270

Changes from all commits

Commits

Show all changes

Select commit Hold shift + click to select a range

docs(sdk): note WS header auth to avoid URL secrets

enyst Jan 22, 2026

docs(sdk): clarify websocket auth headers vs query param precedence

enyst Jan 23, 2026

Update sdk/arch/agent-server.mdx

enyst Jan 23, 2026

File filter

Filter by extension

Conversations

Jump to

Jump to file

Failed to load files.

Loading

Diff view

Diff view

13 changes: 13 additions & 0 deletions sdk/arch/agent-server.mdx

Show comments View file Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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
Expand Down