docs(auth): recommend service account over API key (KLA-407 Slice A)

[jklaassenjc]

Summary

Slice A of KLA-407 — the UX/docs flip. Flips the recommendation in jc setup, jc auth login --help, README, and QUICKSTART so service account (OAuth 2.0) leads and API key is reframed as the legacy/backwards-compat path.

Slice B (OAuth Device Flow for human-bound auth) is platform-blocked and stays tracked in KLA-407 — JumpCloud needs to expose /oauth2/device before we can implement.

Why

User feedback: API keys are long-lived bearer secrets that hold tenant-wide admin privilege. They shouldn't be the recommended path even if they remain available. Service accounts (OAuth client credentials) are easier to rotate, revoke, and scope upstream.

What changed

Setup wizard

• Menu reordered: option 1 is Service Account (OAuth 2.0) — recommended, option 2 is API Key. Default (Enter) is option 1.
• Tests in setup_test.go updated: every test's auth-method choice flipped to match the new order. Test intent unchanged.

jc auth login

• Long help leads with --service-account and explains why; API key block is reframed as legacy / backwards-compat.
• One-line stderr nudge at the top of the API key flow pointing operators at --service-account — visible to anyone running jc auth login interactively.
• --allow-plaintext flag help text now spells out the security risk (config file readable to backups, sync clients, malware) instead of treating it as a neutral fallback.
• Both plaintext-fallback warnings now name the config path explicitly (~/.config/jc/config.yaml) and nudge the operator to fix their keychain.

Docs

• README.md — Authentication Methods section reordered; service account block leads with "recommended for new deployments." API key paragraph reframed as "alternative; legacy." Plaintext-storage risk now bolded.
• docs/QUICKSTART.md — first-run snippet mentions service account recommendation and shows --service-account first.

What's NOT in this PR

• OAuth Device Flow — Slice B; blocked on JumpCloud platform (admin OAuth device endpoint isn't exposed today). Tracked in KLA-407.
• Default flip in CLI behavior — jc auth login without flags still goes to API key flow. Flipping the actual default would break scripted use; the nudge is sufficient for now.
• AUTH.md link from README — already added in PR docs(auth): add docs/AUTH.md — single source of truth (KLA-410) #21 (KLA-410); avoiding a merge conflict by leaving it to that PR.

Test plan

• go build ./... clean
• go test ./... — full suite passing
• setup_test.go — all test cases flipped correctly; menu choice "1" now exercises Service Account, "2" exercises API Key, empty (Enter) defaults to Service Account
• jc auth login --help reads naturally with the reordered long help

Related

• docs(auth): add docs/AUTH.md — single source of truth (KLA-410) #21 / KLA-410 — docs/AUTH.md
• feat(mcp): profile-level read-only enforcement (KLA-409) #22 / KLA-409 — MCP profile-level read-only enforcement
• feat(mcp): step-up auth gate for destructive ops — Phase 1 (KLA-408) #23 / KLA-408 — Step-up auth gate Phase 1

🤖 Generated with Claude Code

---

Note

Low Risk
Mostly user-facing docs/help/UX changes, with minimal behavioral impact limited to interactive prompts and stderr messaging.

Overview
Shifts the recommended authentication path to OAuth 2.0 service accounts across README and Quickstart, reframing API keys as legacy/backwards-compatible and adding clearer security warnings around plaintext credential storage.

In the CLI, jc setup now lists Service Account as option 1 (default on Enter) and API key as option 2, with tests updated accordingly, and jc auth login help text plus warnings now more strongly steer users toward --service-account and explicitly call out plaintext/keychain failure risks (including printing the config path).

^{Reviewed by Cursor Bugbot for commit 771c522. Bugbot is set up for automated code reviews on this repo. Configure here.}