docs(cli): spice login bounds the browser wait and keeps credentials on-origin

[lukekim]

Summary

Four merged runtime PRs changed how spice login handles the browser flow and its credentials, and none of it was documented — the page described only "opens a browser".

• The Spice.ai browser poll is now bounded at 5 minutes (spiceai/spiceai#12523). It previously had no deadline and no attempt bound: an unreachable or wrong SPICE_BASE_URL, a persistent 4xx, or an HTML error page re-looped once a second forever and spice login never exited on its own.
• 404 is retryable, not fatal (spiceai/spiceai#12871, a follow-up to the above). The auth code is minted locally, so the exchange answers 404 until the browser authorization exists — including on the first poll. The deadline still bounds an endpoint that answers 404 forever.
• Credential-bearing HTTP clients follow redirects only within the same origin (spiceai/spiceai#12503, spiceai/spiceai#12508). The auth code, device code, and access token travel in the request body, which a 307/308 replays verbatim to the redirect target, so header stripping alone is not enough and the hop itself is refused.

Changes

website/docs/cli/reference/login.md gains two sections under spice login:

• Browser Login Flow — the 5-minute deadline and its Authentication timed out. Please try again. message, which outcomes stop immediately (Access denied; 400/401/403/410), and which keep polling (5xx, 408, 429, network failures, and 404). Notes that spice cloud login subscription shares the same 5-minute deadline.
• Credentials Stay on Their Origin — the same-origin redirect policy, why the body-replaying 307/308 case is the one that matters, that it covers the spice login flows, the Spice Cloud client, and the CLI's own --api-key requests, and that a refused hop surfaces as the 3xx rather than as a transport error.

Verified against origin/trunk rather than the merged diffs, which matters here — #12871 reclassified an outcome #12523 had introduced days earlier, so the merged #12523 diff alone would have shipped a wrong statement about 404. Sources: LOGIN_POLL_TIMEOUT/LOGIN_POLL_INTERVAL, classify_exchange_status, classify_exchange_body, poll_for_access_token, and credentialed_client() in bin/spice/src/commands/login/mod.rs; same_origin_redirect_policy() in crates/spice-cloud-client/src/redirect.rs, applied at bin/spice/src/context.rs:107, crates/spice-cloud-client/src/client.rs:52, and bin/spice/src/commands/login/mod.rs:486; the cloud device flow's 5-minute deadline at bin/spice/src/commands/cloud/mod.rs:2020. Every quoted message string was grepped in source, not paraphrased.

Source PRs

• fix(cli): bound the Spice.ai login poll instead of retrying forever (fixes #12506) spiceai#12523 — fix(cli): bound the Spice.ai login poll instead of retrying forever
• fix(cli): keep polling when the token exchange has not seen the auth code yet spiceai#12871 — fix(cli): keep polling when the token exchange has not seen the auth code yet
• fix(cli): keep a login credential on the origin it was minted for (fixes #12505) spiceai#12508 — fix(cli): keep a login credential on the origin it was minted for
• fix(cli): follow only same-origin redirects, so the API key cannot leave the origin (fixes #12495) spiceai#12503 — fix(cli): follow only same-origin redirects, so the API key cannot leave the origin

Versioned-docs propagation

Addition — vNext only. All four commits post-date v2.1.4 (tagged 2026-08-05) and git tag --contains is empty for each, so no versioned snapshot describes this behavior.

Test plan

• cd website && npm run build passes (Docusaurus throws on broken links / undefined tags)
• Versioned-docs propagation checked — addition, vNext only
• Files updated: 1

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: lukekim

[github-actions]

🚀 deployed to https://79c8aea9.spiceai-org-website.pages.dev