[oh-tab-a1g] Docs: WS header auth (no URL secrets)

[enyst]

Fixes oh-tab-a1g.

Updates cloud auth / agent-server protocol docs to reflect the security posture: no secrets in WS URLs.

• Prefer WS header auth for non-browser clients (X-Session-API-Key / Authorization: Bearer ...).
• Keep ?session_api_key=... documented only as a legacy browser constraint.
• Cross-links upstream blockers agent-server: allow WebSocket auth via headers OpenHands/software-agent-sdk#1786 + sdk docs: mention WS header auth (avoid URL secrets) OpenHands/docs#270 and downstream PR [oh-tab-h3g] Security: drop session_api_key from RemoteConversation WS URL #873.

Notes

• This is documentation-only; does not change runtime behavior.

---

Summary by CodeRabbit

• Documentation
  • Clarified API authentication for HTTP and WebSocket handshakes.
  • Prefer header-based auth (X-Session-API-Key or Authorization Bearer) for non-browser clients.
  • Preserve legacy browser-only WebSocket query-param fallback (?session_api_key=...) where required.
  • Advised avoiding secrets in URLs and updated WebSocket URL construction guidance.
  • Clarified cloud vs runtime/session token usage and updated device-flow and settings guidance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Documentation updated to prefer header-based authentication (X-Session-API-Key or Authorization: Bearer) for HTTP and WebSocket handshakes in non-browser contexts, while preserving a legacy ?session_api_key query-parameter fallback for browser WebSocket usage and clarifying cloud vs runtime/session token roles.

Changes

Cohort / File(s)	Summary
WebSocket & API auth docs docs/PRD.md, docs/agent_server_test_matrix.md, docs/cloud-auth-flow.md, docs/cloud_oauth_device_flow.md, docs/settings_prd.md	Replaced guidance that placed ?session_api_key in WS URLs with header-based authentication during the WebSocket handshake (X-Session-API-Key or Authorization: Bearer) for non-browser clients; added explicit legacy browser-only ?session_api_key fallback, updated WS URL examples, and clarified cloud vs runtime/session token roles and retrieval points.

Sequence Diagram(s)

(omitted — documentation-only changes; no new multi-component control flow introduced)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• [oh-tab-a1g] Docs: WS header auth (no URL secrets) #874: Same documentation change switching WS auth from ?session_api_key to header-based auth with a browser query-param fallback.
• Add settings_prd.md: agent-sdk grounded settings, VS Code split #19: Related edits concerning constructing WS URLs and session_api_key handling (query-param vs header).
• Update /audit AgentSkill for current security model #856: Overlapping updates to docs regarding sessionApiKey usage and header-based WebSocket authentication.

Poem

🐰 I hopped through docs with a careful tweak,

Headers for handshakes — tidy and meek.
Browsers keep a secret, tucked in a curl,
Non-browser headers unfurl like a pearl.
No secrets in URLs — hop, skip, and twirl.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: updating WebSocket authentication documentation to use headers instead of URL secrets.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 2 additional flags.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@docs/cloud-auth-flow.md`:
- Around line 26-34: Replace the bolded "Related work (Jan 22, 2026)" line with
a proper Markdown heading (e.g., "## Related work (Jan 22, 2026)" or "###
Related work (Jan 22, 2026)") so MD036 is satisfied and the section matches the
doc's other headings; update the line that currently reads "**Related work (Jan
22, 2026)**" to a heading-level line and ensure the surrounding list items and
paragraphs remain unchanged.

In `@docs/settings_prd.md`:
- Around line 24-26: Add a short clarifying sentence next to the "WebSocket:
prefer handshake header auth" line and/or adjacent to the WS URL example to
state that the `?session_api_key=<runtimeSessionApiKey>` query parameter is
legacy-only (browser-only) and will be removed upstream; reference the
`session_api_key` token explicitly so readers know the query-param example is
deprecated and header auth (`X-Session-API-Key` or `Authorization: Bearer ...`)
is the recommended approach.

[github-actions]

🔧 VSCode Extension Built Successfully

• File: openhands-tab-0.8.0.vsix (526 KB)
• Download: https://github.com/enyst/OpenHands-Tab/actions/runs/21240825381

To install:

1. Download the artifact from the run page above
2. VS Code → Command Palette → "Extensions: Install from VSIX..."
3. Select the downloaded .vsix

Built with Node 22. Commit 2386509.